Contents
This document describes the standard workflow for nipy development using bazaar and the launchpad hosting service. It would help very much in keeping track of shared code if all nipy developers adopt this workflow. The workflow should be flexible enough that even an occasional developer can contribute code to nipy since it does not require all contributors to have commit access to the main trunk. This particular workflow was developed to achieve these primary objectives.
The diagram describes the usual workflow:
We describe the various parts of this diagram in the following sections.
On launchpad, there exists one main nipy trunk that only an administrator has commit access to (see nipy bazaar administration). All developers have their own launchpad.net/~developer directory which may be registered with the nipy project. In addition, there may be shared team directories on nipy, for feature development, but in general individual development should happen in your ~developer directory.
A snapshot of the nipy code directories on launchpad
Your development directory will contain at least one branch:
where trunk-dev is a branch from your user directory on launchpad and is your working development branch.
We’re using the shared repository feature of Bazaar and a Decentralized with human gatekeeper workflows. The basic process is as follows:
Create an account on launchpad, if you don’t have one already. Follow the Log in / Register link on the top of the page.
Create a shared repository:
bzr init-repo --trees nipy-repo
cd nipy-repo
bzr whoami “Barack Obama <bobama@whitehouse.gov>”
Create your own personal development branch, named trunk-dev, by replicating the nipy trunk:
bzr branch lp:nipy trunk-dev
Push your development branch up to launchpad for backup and to make your changes visible to the rest of the team:
cd trunk-dev
bzr push bzr+ssh://USER@bazaar.launchpad.net/~USER/nipy/trunk-dev --remember
Real example of the line above for user cburns:
bzr push bzr+ssh://cburns@bazaar.launchpad.net/~cburns/nipy/trunk-dev --remember
You now have your own branch, stored on launchpad, and on your machine, in which you can develop nipy code. If you get an error while trying to push, see the Push Error: Permission Denied (publickey) document for instructions on launchpad and your ssh key.
You will usually want to keep track of changes in the nipy trunk. To do this, you will often want to merge the nipy trunk into your development branch:
cd trunk-dev
bzr merge lp:nipy
bzr commit -m 'Merge from trunk'
When editing you will want to push your changes up to your launchpad branch:
cd trunk-dev
# edit code
bzr ci -m "Add a meaningful summary of your edits in one complete sentence."
# repeat
...
# periodically push to lp:~user (like end of day)
bzr push
Since we are all doing development in our own launchpad branches, each developer should keep their branch up-to-date with the main trunk so their branch doesn’t diverge significantly from the rest of the team. This is done with the bzr merge lp:nipy line in the Daily development cycle section above. Launchpad allows developers to subscribe to a branch and receive email notifications when there are changes. By subscribing to the nipy trunk, you will be emailed whenever the trunk changes, reminding you to merge the trunk into your branch.
On the nipy trunk page there is an Owner / Subscribers section on the right-hand side. Click on the link Subscribe yourself. Select the desired options and click the Subscribe button.
These options should be sufficient for developers:
- Notification Level:
- Branch attribute and revision notifications
- Generated Diff Size Limit:
- Don’t send diffs (more below)
- Code review Level:
- Email about all changes
The Diff Size Limit is a personal preference. The full diff’s can be long and a lot to read in an email. I find it easier to view the changesets on Launchpad with the color-coded diffs.
Note: Developers can also subscribe to other team members branches.
In order to do code reviews, each developer should propose their developer branch for merging into the nipy mainline. We have decided to keep these proposed merges open indefinitely so the code reviewer can use Launchpad to view branch changes prior to pulling the branch. You only need to do this procedure once.
In your developer code directory, select the Propose for merging into another branch link and choose these options:
- Target Branch:
- The NIPY mainline (default selection)
Click on the Register button.
Edit the branch Title and Summary. In your branch page, select the little yellow circle with the pencil icon next to the title to Change branch details. Set the options to something like:
- Title:
- Chris’ development copy of the nipy trunk
- Summary:
This branch is my development copy of the trunk. It is available here for review by other developers, and merges will be periodically made into trunk.
For this reason, it will always be marked for review to be merged.
- Status:
- Development
Click on the Change branch button to finalize.
Look at Chris’ branch for an example.
The bzr documentation is thorough and excellent.
Benjamin Thyreau also kindly posted a bzr tutorial in French.
And we’ve start a collection of Bazaar Tips for some common questions.