Bzr usage

Code is controlled using the bazaar Distributed Version Control System. Before writing code, developers should checkout a copy of the maus trunk (lp:maus). Developers should then make their own development branch on launchpad as outlined in the MAUS wiki. Code should be pushed regularly to this development branch (typically nightly). Every release, the MAUS trunk should be merged with the development branch to ensure that development is performed against the latest MAUS version.

Basic Bzr Guidelines

Basic guidelines:
  • All development is done in branches (one branch per dev)
  • Once a branch passes all tests, it can be merged with the trunk
  • Once you have merged with the trunk, you should take changes of other developers (i.e. the trunk) back into your branch

Provided here are instructions to help new developers come into the project.

bzr and DVCS

DVCS means distributed version control system. We use a DVCS to let multiple developers work on different aspects of the code in parallel.
  • Each parallel development stream is described as a branch.
  • The main flow of the code is described as the trunk. The trunk is where we take versions that can be used for batch production jobs, control room operation etc.
    • All new code added to the trunk should be checked in one or more test. All tests should always pass in the trunk.
    • All new code added to the trunk should pass cpplint.py with no warnings.
    • All new code added to the trunk should obey the style guide - there are some style requirements in the style guide that are not (and cannot) be checked by cpplint.py
    • All new code added to the trunk should not generate any compiler warnings
    • If your code modifies or exposes a user interface (either changes an output file or uses an input file), this must be documented in the documentation
  • Full releases are stored in branches.

Setting up bzr and launchpad

  • You should install a recent version of bzr.
  • You can get your bzr version by doing bzr --version
  • You can get bzr from http://bazaar.canonical.com/en/ or usually apt-get or equivalent has a bzr version
  • You need to set up a launchpad login and ssh keys at the launchpad website (https://launchpad.net/).
  • Once you have a login, do
    bzr whoami "John Smith <john.smith@rl.ac.uk>"
  • At RAL, you will should make sure your proxy is set by doing
    export https_proxy=http://wwwcache.rl.ac.uk:8080   ### Only if you are at RAL
  • To use launchpad you will need to set your ssh rsa key. You can generate a ssh rsa public - private key pair from the linux command line using:
    ssh-keygen
    Make sure you set a good password when given the option (too weak and the process will fail). This then generates two files, id_rsa (your private key) and id_rsa.pub (your public key). Both files should be put in the (hidden) directory:
    ~/.ssh/
    You will need to set the permissions on the files too, using the following:
    chmod 600 id_rsa
    chmod 640 id_rsa.pub
    
    For the interested reader, there is a nice chmod tutorial available at http://catcode.com/teachmod/ .
    Upload the text of your public key to your launchpad account, and you are good to go.
  • Once you have set up your key, you will be able to connect bazaar to your launchpad ID with:
    bzr launchpad-login jsmith

Getting MAUS and branches

You should have at least a local development copy of the maus trunk and your personal maus branch. You will probably want a copy of the latest release branch also for patching.
  1. To get a copy of the trunk, do
    bzr branch lp:maus/merge 
    (To get a copy of the release branch, do
    bzr branch lp:maus 
    )
    • Pro-tip: bzr is slow if you don't set up your bzr login - it uses a poor http thing rather than fast ssh thing.
  2. Move that to a folder like maus-something so you don't get any name clashes if you want to check out another copy.
  3. Ask <> for:
    • a login on the test server
    • a test job for your branch
  4. Make a new issue in the Issue tracker by clicking on "New Issue" link or take ownership of an existing Issue. Note the Issue number
  5. Make a development branch, by doing
    bzr push lp:~<username>/maus/<issue number>
    • If you don't have a launchpad <user-name>, you can get one from the launchpad website
    • If you are at RAL (not on eduroam or STFC-Facilities-Users), you need to set $http_proxy environment variable to http://wwwcache.rl.ac.uk:8080, or alternatively a longer version of the branch command may work:
      bzr branch bzr+ssh://bazaar.launchpad.net/%2Bbranch/maus/merge
  6. You can have as many branches as you have open issues (or any other branches you want). It is a good idea when developing to keep separate branches for each feature, bug fix etc you are working on. If you do expect to use several branches at the same time (e.g. one for the latest stable release, one for featureX development, one for featureY development) then consider setting up a shared repository for maus. See http://wiki.bazaar.canonical.com/SharedRepositoryTutorial for more.

Now get developing!

Committing changes to your development branch

Develop in your development branch. Check in at least once a day. When your changes are ready (passes all tests), merge with the trunk.

Your development branch is your working branch where you make changes and hack code. You make changes on your hard drive, and push these to the development branch so that other developers can see what you are doing and so that the test machine can see what you are doing (and you get a report every time the test server does a build/test job).

If working on different features at the same time, consider using a separate feature branch for each, to keep things tidy and make the audit trail more transparent.

To push changes made locally to the server, do

bzr commit -m '<Description of changes>' <file1> <file2> ...
You should make a nice description in the commit message and specify the file names where the changes have been made. For those used to CVS, bzr works on all directories in the branch, rather than acting recursively from the current directory. So you should specify filenames.

When you want your changes to be public, then you need to run

bzr push
which will push your changes online (but not into the trunk) such that they can be tested by our central testing.

You can either email <> to merge your changes with the trunk or do it yourself.

Merging changes from the trunk to your branch

Worth merging from trunk at least every time there is a new minor release to keep your feature branch close to the trunk. The minor releases are announced on mice-software mailing list.

  1. Go to a copy of your branch
  2. Comit any of your changes as above
  3. Do
    bzr merge --preview lp:maus
    to see what the result of your merge will be.
  4. Do
    bzr merge lp:maus/merge
    to pull the trunk into your branch and bzr will put a diff of the conflicts in your working directory. Each file with a conflict will get lines like
    +<<<<<<< TREE
    <text from YOUR branch>
    +=======
    <text from the trunk>
    +>>>>>>> MERGE-SOURCE
    
  5. Go through, fix the diffs, then do
    bzr resolve <file1> <file2>
  6. Commit code as above.

Merging changes from your branch to the trunk

See the guide at Merging code to the trunk.

Advanced Usage

This stuff is only needed by code administrators.

Making a new Development Team

To make a new development team (for example, for a group of people working together to code in a particular detector).

  1. Log in to Launchpad.
  2. From the launchpad front page click Register a team and select the options. Name would typically be something like maus-<detector-name>
  3. Make a new branch from the trunk
    bzr branch lp:maus
  4. Push it to bzr:
    bzr push --remember lp:~maus-<detector-name>/maus/devel
  5. Check that it worked
    bzr info

Bazaar Tips

  • bzr blame filename.cc can be used to see who lasted edited each individual line of a file under version control
  • bzr info displays default push and pull locations for the current branch, together with other useful info
  • bzr status displays any files modified since the last commit

Notes

There are two ways to use Bazaar that require a slightly different syntax.

bzr branch lp:maus
makes a child branch of lp:maus and subsequent revisions can be sent back to the parent branch using
bzr commit -m 'some message'
bzr push

Meanwhile

bzr checkout lp:maus
makes a local copy of lp:maus and subsequent revisions can be copied back to the server using
bzr commit -m 'some message'
.

Bzr can make a tangled mess. Generally, most things can be recovered by doing

bzr bind lp:some_branch
which makes the commit location lp:some_branch. Then you can do
bzr commit -m 'some message'
to put your code on the server.

If you want to change the default push, pull or merge location, try something like

bzr push --remember lp:~me/my-branch

See also