BZR Logo

BZR Workflow

This document covers fixing a Launchpad bug for software located in bzr. For the purposes of this document we will fix a bug in

After going through this document, you may want to drill down into more details about Launchpad and BZR. You can find an excellent article here:

NOTE: Canonical has some good materials for people new to bzr that have used other VCS's:

Setting Up Your Sandbox

To start fixing a bug you must first create a local branch to do your fix in. Generally you'll pull from the trunk.

#ensure you are identified properly
$ bzr whoami

#set up your lp login
$ bzr lp-login <launchpad-id>

#once your ID is correct, grab the code[*]:
$ bzr branch lp:linaro-image-tools
$ cd linaro-image-tools

[*] See l-m-c for complete instructions

NOTE: There could be a case where your fix depends on another person's fix. In that case you'd create a branch from that.

NOTE: If your branch has a long revision history, you may consider using a Shared Repository

If you anticipate needing to work on multiple branches of a given project, you might want to read this article that makes the workflow even easier:

Creating the Fix

For this document let's pretend we need to update the email address from linaro-dev to Linaro-DEV:

# Use bzr's grep to find the occurrences:
$ bzr grep linaro-dev
COPYING:Maintainer: Linaro Infrastructure team <linaro-dev@linaro.org>
hwpack/tests/test_config.py:        maintainer = "Linaro Developers <linaro-dev@lists.linaro.org>"
setup.py:        author_email="linaro-dev@lists.linaro.org",

#update these files with:
$ sed -i -e 's/linaro-dev/Linaro-DEV/g' COPYING
$ sed -i -e 's/linaro-dev/Linaro-DEV/g' hwpack/tests/test_config.py
$ sed -i -e 's/linaro-dev/Linaro-DEV/g' setup.py

NOTE: If bzr grep is not recognised, you will need to do a sudo apt-get install bzr-grep

You now have some "dirty" files. You can see what's changed from both your shell and graphically:

$ bzr status
modified:
  COPYING
  hwpack/tests/test_config.py
  setup.py
$ bzr diff COPYING
=== modified file 'COPYING'
--- COPYING     2011-01-28 19:53:07 +0000
+++ COPYING     2011-02-02 22:34:49 +0000
@@ -1,6 +1,6 @@
 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
 Name: Linaro Image Tools
-Maintainer: Linaro Infrastructure team <linaro-dev@linaro.org>
+Maintainer: Linaro Infrastructure team <Linaro-DEV@linaro.org>
 Source: https://launchpad.net/linaro-image-tools
 
 Files: linaro-hwpack-create linaro-hwpack-install hwpack/*

Graphically (by running meld ./):

meld comparing

Committing the Fix

Now that the files are updated correctly, you can commit the changes. Remember, bzr is a distributed VCS so a commit will not make any changes to Launchpad.

# assume you have a lp bug #987654321:
$ bzr commit --fixes lp:987654321 -m "Updated email address for no good reason" COPYING setup.py hwpack/tests/test_config.py 
Committing to: /home/doanac/linaro/code/linaro-image-tools/                    
modified setup.py
modified hwpack/tests/test_config.py
modified COPYING
Committed revision 286.

# To see what changes the commit made you can run:
$ bzr diff -c 286

#NOTE: If you forget to include something in this fix and would rather not
# make a second commit to fix this, you may run:
$ bzr uncommit
#fix the file
bzr commit --fixes lp:987654321 -m "Updated email address for no good reason" COPYING setup.py hwpack/tests/

Now your fix has been committed and will show in your log:

$ bzr log -l1
------------------------------------------------------------
revno: 286
committer: Andy Doan <andy.doan@canonical.com>
branch nick: linaro-image-tools
timestamp: Wed 2011-02-02 14:55:09 -0800
message:
  Updated email address for no good reason

You can visually inspect the history with bzr visualize:

bzr visualize

Sharing Your Fix

You now want to share your branch with Launchpad so it can be reviewed and then merged into trunk to fix the bug. You do this by creating a personal branch on Launchpad:

# the format of the push argument is normally:
#  lp:~<launchpad id>/<project>/<short name for fix>
$ bzr push lp:~doanac/linaro-image-tools/my-email-fix

To get your code merged in you must do a "merge proposal". You can do this by going to your launchpad code page:

your launchpad code

You can then click on the branch you want to initiate a merge proposal for. That page will have a link "Propose for merging":

propose a merge

After filling out the form and clicking "Propose Merge" a review will be set up. If this merge depends on another branch in the queue select that as "pre-requisite" from one of the extra options in the drop-down.

In addition to creating merge proposals using the Launchpad web interface you can also do this through the command line with:

$ bzr lp-propose -R linaro-maintainers lp:linaro-image-tools

Merging

If you've been working on a branch for a while and other changes have come in to the master, you'll want to periodically merge to keep your code up-to-date. You can view a short tutorial on merging here

Once you submit a merge proposal the maintainers will be alerted and can review your changes. There are a few directions things can go at this point:

The Ideal Way

If your code is exactly right, a maintainer will merge your branch into the trunk. At this point, you are done!

Minor Update Requested

Often the reviewer will add some notes about how your fix should be changed. Launchpad will email you these notes as they are added by the reviewer. You can respond to any questions by replying to the email (or via the launchpad web interface).

If you need to make minor changes you'll have to go back to your local repository (don't worry if its been deleted, you can run  bzr branch lp:<YOUR BRANCH>  to get it back.

After making the required updates, do a new commit and then run bzr push to get the update onto Launchpad. At this point the reviewers will be notified and can merge your changes into trunk.

Major Update Requested

Sometimes the updates requested might be in a way that your original branch changes no longer make sense. In that case you can create a new branch, do your fix(es) and then push this branch to Launchpad. Once the branch has been pushed, you can add a note to the current merge proposal pointing it to your new branch. Then you can submit a merge proposal for that branch and go through the normal process of getting your branch merged.
Note: You can also re-request a merge in the merge proposal page by selecting the Resubmit proposal option.

Here is an example of a big review that went through multiple iterations: slash-proc-spam-version2

Observations From a Git User

Here are some things I found different about this process coming from a background in Git.

  • After copying the branch (ie bzr branch lp:linaro-image-tools), you don't then create a local branch to do your changes on. This is because you are already on the local branch. Despite that it still felt awkward at first.
  • A bzr branch is a directory. You don't switch between branches from a single directory like you do in Git. So if you are working on 2 different fixes, you'll have two different bzr branches (directories)
  • There's no rebasing. Most git users will pull from a remote repository to get up-to-date and then rebase their changes on that until they are ready to publish the changes.
  • Although there's no rebasing, if you're working on a branch long enough that other changes were committed to your parent branch in the meantime, you should merge the parent branch every once in a while (probably as frequently as you'd rebase) to make sure you've no conflicts and your code works with the latest trunk
  • A merge in bzr does not automatically create a commit like it does in git. You must run "bzr commit" after successfully doing your merge. For more details see bzr merge conflict.

  • I found the Bazaar for Git Users article to be very helpful


CategoryBzr

Resources/HowTo/BZR (last modified 2011-05-03 16:52:04)