Actions

History

Bzr usage¶

Table of contents
Bzr usage
Advanced Usage
- Making a new Development Team
Bazaar Tips
Notes
See also

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.

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.
Move that to a folder like maus-something so you don't get any name clashes if you want to check out another copy.
Ask <maus-dev@jiscmail.ac.uk> for:
- a login on the test server
- a test job for your branch
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
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
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 <maus-dev@jiscmail.ac.uk> 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.

Go to a copy of your branch
Comit any of your changes as above
Do
```
bzr merge --preview lp:maus
```
to see what the result of your merge will be.
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
```
Go through, fix the diffs, then do
```
bzr resolve <file1> <file2>
```
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).

Log in to Launchpad.
From the launchpad front page click Register a team and select the options. Name would typically be something like maus-<detector-name>
Make a new branch from the trunk
```
bzr branch lp:maus
```

Push it to bzr:

bzr push --remember lp:~maus-<detector-name>/maus/devel

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

Project

General

Profile

Wiki