wiki:OurSubversionGuidance

Version 6 (modified by astephen, 9 years ago) (diff)

--

Our Subversion Guidance

These are the conventions that NDG2 partner developers should use when utilising the Subversion repository:

The NDG subversion repository structure

Explanation

  1. There are Product level directories hanging off the top level ‘ndg’ directory. For example TI01-discovery, TI02-CSML etc. Each one of these will have ‘trunk’, ‘tags’ and ‘branches’ sub-directories.
  2. The ‘trunk’ directory contains the main development trunk for that product. The HEAD of this main trunk is what most people will checkout when they are going to do further development on the code or documents within. It can be considered unstable as regards installing in an environment where you expect it all to work with predictable results. Development work should be committed regularly (daily). A good rule of thumb is “a single commit (changeset) must not be so large so as to discourage peer-review. "
  3. The ‘tags’ directory should contain snapshots of the main development trunk at a stage where it is considered stable. This means that it has been tested (unit, system and potentially Working Grid tests). Each snapshot of the product should be named according to the convention : ’stable-TIxx-name-vx-x’ for example ‘stable-TI01-discovery-v1.0’ is the version 1.0 stable snapshot of the Discovery product. The log entry used when creating the tags snapshot should give further detail of why this was created e.g. “Tested in glue dev environment with DIFs containing access constraints”. The ‘tags’ directories will not be read-only as this would have to be done via unix groups and would interfere with the way Subversion expects to work. We will stick to the convention that things in tagged directories should not be changed, only downloaded.
  4. The ‘branches’ directory may contain feature branches – special featured development of the main trunk. For example, special requirements in the CSML product for the Met Office. The contents of these feature branches may or may not be merged back into the main trunk at some point. More likely they will have main trunk changes merged into them. It is up to the developer to decide if a feature branch is required and to annotate them with logs accordingly and manage them.
  5. There is also a ‘releases’ directory hanging off the top level ‘ndg’ directory. This is where official named releases of software should be constructed. Stable snapshots should be selected from product tags directories and constructed into a release under this directory. At the moment it is merely indicated that NDG2 requires at least an Alpha and Beta release. These releases will have to contain scripts which install the actual software into a Data Providers environment. We may therefore have configuration specific releases.
  6. Sub-products – it is recognised that a formal NDG2 product may have logical sub-products which develop on different timescales. For example, TI02-CSML product will have application schema work and parser work ready at different times. Therefore we are allowing sub-product directories to have their own tags directory enabling stable snapshots of sub-products to be available. Naming as before e.g. ‘stable-TI02-CSML-parser-v1.0’. These stable subproduct names should map onto the keywords used for tickets and be clearly identified on the product top level pages.

Important Tips

  1. MS Word docs and images (.gif .jpeg etc) will be saved as binary files. They therefore need to have a mime-type property set to ‘application/octet-stream’ to be correctly interpreted by Subversion. SVN Clients may set this correctly when a new such document undergoes ‘svn add’, but they may not. You must check the mime-type property in your client before committing. The command line check is : svn proplist -v yourworddoc.doc. To set the property: svn propset svn:mime-type "application/octet-stream" yourworddoc.doc
  2. Note that binary documents cannot be ‘line compared’ and therefore merged. The effect of this is that care should be taken when two people may be changing the same binary document. For us this is most likely to affect word documents. See the  svn book for more details.
  3. Filenames with mixed dots & slashes can cause problems. We found that some files in nappy were named ‘/ndgsvn/nappy/trunk/test/..\testfiles\1001.na’. These caused problems when checking out with a windows client (linux command line seemed OK). Do not use such filenames and remember windows/linux differences. e.g. don’t have MyFile.txt and myfile.txt in the same linux directory and don’t have spaces in windows filenames.

See also:

Attachments