Wales Group Version control

From Docswiki
Jump to navigation Jump to search

As of 16th July 2008, all the group code is under version control. GMIN, OPTIM and PATHSAMPLE, along with the CHARMM and AMBER code used with them have been added to the repository, along with the official documentation. Changes to the documentation in the repository are automatically applied to the version on the website every night (at midnight) and the RSS feeds below are updated every ten minutes. The next step is to set up the nightly compilation and test suite for each code.

There are instructions on how to set up your SVN details and obtain the group code on the SVN setup page.

RSS feeds

RSS feeds (including diffs of files that have been changed) are generated every 10 minutes from the SVN log files any uploaded to the Wales group web server here. There is currently one feed per top level directory in the repository:

  • trunk_log.xml - contains the logs/diffs for every change to the code
  • gmin_log.xml - only contains the logs/diffs when code in the GMIN directory is changed
  • pathsample_log.xml - only contains the logs/diffs when code in the PATHSAMPLE directory is changed
  • optim_log.xml - only contains the logs/diffs when code in the OPTIM directory is changed
  • charmm_log.xml - only contains the logs/diffs when code in the CHARMM31 directory is changed
  • amber_log.xml - only contains the logs/diffs when code in the AMBER directory is changed
  • nab_log.xml - only contains the logs/diffs when code in the NAB directory is changed
  • disconnect_log.xml - only contains the logs/diffs when code in the DISCONNECT directory is changed
  • doc_log.xml - only contains the logs/diffs when code in the DOC directory is changed
  • scripts_log.xml - only contains the logs/diffs when code in the SCRIPTS directory is changed
  • ambertools_log.xml - only contains the logs/diffs when code in the AMBERTOOLS directory is changed

Using Firefox to look at the feeds is ok, but I suggest you set up a different RSS reader, such as Google Reader to keep them all in one place. Note that Google Reader has a delay in updating the feeds, so you won't see new logs up to an hour after they are created and are visible with Firefox.

Access restrictions

Raven authentication has been re-enabled for the diffs only. You can view the feeds without logging in (as this allows email clients to be used), but if you are outside the department, you will need to log in via Raven to access the diffs linked from the feed. Also, the diffs directory is now excluded from Google and other bot searches. This should hopefully prevent chunks of code ending up on Google.

Usage tips

What follows are a few suggestions to make using SVN a joyful experience (see cautionary tale below, to illustrate how it can go wrong). Please add any others you think are important! In general you should:

  • please be careful with svn commands. svn is a very powerful tool, and it is possible to revert all changes made over a long period, which is probably not what you want. Please consult before you revert changes made by other people.
  • make sure you followed the setup instructions on the SVN setup page. The procedure includes setting up a template file to ensure that all logs are in the same basic format
  • run 'svn update' on a regular basis to ensure you have the latest bug fixes. It is also important to update regularly to detect any bugs that may have appeared due to changes elsewhere in the code. Please report any changes in behaviour that might indicate bugs.
  • always do an 'svn update' before you do 'svn commit'
  • don't forget 'svn add <filename>' to schedule a new file for addition at the next commit!
  • get into the habit of running 'svn diff' before committing. And looking closely at the output... Optionally, run 'svn diff | grep Index' to see a summary list of the files that you have changed. Try not to commit extra things you didn't mean to.
  • commit your changes regularly. If you wait a two months before commit your changes, you're likely to have to resolve more conflicts in parts of the code that has been changed by others in the meantime.
  • if you get a conflict (C flag) when running 'svn update', find out who introduced the change and talk to them about it to make sure you can introduce your code without damaging theirs.
  • consider making a development branch (more on this on the SVN setup page) if your hacking is going to involve a lot of potentially disruptive changes over a significant period of time. Talk to DJW and current developers about this first though...
  • to obtain a previous version of one file. In the svn directory where that file lives use svn -r with the revision number, the file name, and pipe the output to a target. For example, to obtain revision 36240 of commons.f90 use

svn -r 36240 cat commons.f90 > commons.f90.36240

  • to see a log of svn commits use svn log in the appropriate directory. The log contains the changes entered by the user who made the commit. Please fill in relevant fields for the log when you make changes.

Cautionary Tale

In August 2019 the author of this section (namely me) made an svn error that could have had potentially very damaging consequences. Being inexperienced with svn I followed the instructions to revert back to a previous version of the code, thinking I was just rolling back my own personal repo, clearly this was not the case and the whole repo was reverted back to a version from February 2019.

If caught quickly this error is quick and easy to fix, however the missing features, which had been added between February and August were only noticed in Jan 2020. This meant that people had committed code to a much older version of the code and everything was out of line. Fortunately in this case some crafty svn work from John was able to put it right without too much pain, but lessons should be learnt. At this stage I just want to say a quick sorry for the trouble caused and feel like I've at least learnt from it.

Lessons to be learnt:

  • ask for advice from more experienced members when committing if you're unsure.
  • try to make regular updates to your personal repo so that these errors can be spotted more quickly in the future.

Papers

We have a repository for preparing papers too: see Papers_in_preparation for information.

Retrieved from "http://wikis.ch.cam.ac.uk/ro-walesdocs/wiki/index.php?title=Wales_Group_Version_control&oldid=1565"