BZR and Launchpad

In March of 2010 the Sahana development community migrated from CVS and Sourceforge to using BZR and Launchpad. Below are relevant reference materials, instructions, and guidelines for using BZR and Launchpad for development of Sahana.

• https://launchpad.net/sahana - Main homepage for Sahana on Launchpad
• https://launchpad.net/s3 - Sahana Py project
• https://launchpad.net/sahana-php Sahana PHP project

• Sahana Disaster Management System Project. This is the parent project on Launchpad for Sahana. The LP team for this project is the Sahana Team. The project is administered by the Sahana Admin Team.
• SahanaPy. This is a series for the development of Sahana in the Python Language. The code is a series of the Sahana Project, and is managed by the SahanaPy Team
• Sahana Relief Experiments Project. This is a special project that is used temporarily during the year for the Camp Roberts RELIEF experiements. This project will be very active for the duration of the experiments, and probably a week before and after. Outside of this it will not be used. Sahana trunk will be uploaded a week before the experiments, and then the relief-experiments branch will be used actively for the next few weeks by those contributing to the work. At the end of this period, a merge proposal will be proposed to ensure all the modifications are quickly submitted back to Sahana trunk.The LP team for this project is the Sahana RELIEF Team.
• Sahana Review Team. This is a team that is responsible for branch merge proposals. It is responsible for reviewing the quality of code submitted for the merge, and approving or disappoving the merge request. (20091117: at this point it is a new team and the full policy around code review/merge proposals has yet to be completely worked out. It is also currently tied to the RELIEF experiments only.)
• New Zealand Sahana Cluster. This is a team formed to focus on the development and deployment of Sahana in New Zealand, Australia and the South Pacific.

All of the Sahana bzr branches in LP can be found here: All Sahana branches.

Sahana currently has three main 'series' stored on Launchpad. These are:

• SahanaPy - for the development of Sahana in the Python language.
• SahanaMobile - a GSOC2009 project to create a Sahana application in J2ME for the OpenMoko platform.
• Sahana RELIEF Experiments - a development effort to focus development during the RELIEF Experiments at Camp Roberts.

In addition to the main development series, there are a wide range of personal branches available as well. These are listed on this page underneath the branches marked series. Personal branches have a '~username' in their title.

(draft) The following is the recommended approach to managing the editing and contribution of code to the various projects using LP/bzr.

To download a branch of an existing Sahana series to your local computer, you would issue a command like the following.

bzr branch lp:sahana
bzr branch lp:sahana/sahanapy
bzr branch lp:sahana/sahana-mobile
bzr branch lp:sahana/relief-experiments

The above commands will download each branch to a newly created directory in the current working directory - sahana, sahanapy, sahana-mobile and relief-experiments.

(would like someone with more experience to outline bzr add/remove/commit as a precursor to uploading the branch to LP.

To upload your personal branch to bzr, you need to register a new branch and upload the code. This can be accomplished from the commandline with a single command. First, change into the folder that contains the code.

bzr push lp:~username/sahana/branchname --use-existing-dir

For example, if I wanted to create my own personal branch for RELIEF experiments from a branch that I'd downloaded, I would use the following command.

bzr push lp:~gt/sahana/relief-experiments --use-existing-dir

The –use-existing-dir forces the code on your computer to be uploaded as a new branch, whilst keeping all the existing commit information from your local files. Note: to be able to propose personal branch merges into series, it is recommended that you stick to the ~username/sahana/seriesname format - /sahana/ is the most important to enable this.

Once you have committed your code back to your personal branch, and you're willing to have your code reviewed and considered for merging into a series, you can 'Propose your branch for merging'. To do this, visit your LP page for your branch, e.g. https://code.launchpad.net/~username/sahana/branchname and click Propose for Merging. On the form page, you can select the target branch you want to suggest the merge to. The review team should be selected as the Sahana Review Team.

In the PHP Project, there are two groups involved for development: sahanaphp-pmc is the Project Management Committee group and sahanaphp-committer is the Committers group. The Committer group is the maintainer of the PHP branches and the PMC are default reviewers of proposed mergers. Committers submit merge proposals to the branches before it is committed so the community can review code and make comments before it is approved.

Everyone with a Launchpad ID is welcomed by the Sahana Community to review merge proposals and make comments. If you would like to contribute code, but are not a Committer, you can submit it to the MainDev mailing list for review, feedback, and possible merger.

Launchpad has more detailed instruction for code review and merger; however, step by step instructions are listed below.

• Visit the branch overview page. To find this page, begin at the PHP or Py project homepage, click Branches at the top, then click the link for the branch you're working on from the list.
• Under the heading “Branch Merges” click the link “Propose for Merging” and follow the on-screen prompt.
• Launchpad will notify anyone watching this branch of your proposal.

Note: If you are not a Committer, please e-mail your changes to the MainDev mailing list. If you're not a member of the list visit the mailing list wiki.

Anyone with a Launchpad ID can be part of the code review conversation. The community as a whole appreciates your respectful and constructive criticism.

There are two parts to a review: votes and a threaded conversation very similar to a forum discussion. If you're a subscriber to the branch you'll receive an e-mail whenever someone votes or makes a comment. There are two ways to contribute:

• Visit the discussion by clicking the link in the e-mail.
• Reply to the e-mail with your comments to be added to the discussion. There is a detailed list of commands at the Launchpad review instructions list.

Once the code has been reviewed and either accepted for merger or rejected (hopefully with useful feedback) the Committer group is ready to merge.

Detailed merger instructions are available for reference in the BZR canonical documentation. *The merge command is used to perform the merger:

bzr merge [URL]

If you have any questions or would like some assistance feel free to contact the Sahana PHP PMC or Committers.