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 <firstname.lastname@example.org> hwpack/tests/test_config.py: maintainer = "Linaro Developers <email@example.com>" setup.py: author_email="firstname.lastname@example.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 <email@example.com> +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 ./):
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 <firstname.lastname@example.org> 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:
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:
You can then click on the branch you want to initiate a merge proposal for. That page will have a link "Propose for merging":
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
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
Navigating the Code Review
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
Resources/HowTo/BZR (last modified 2011-05-03 16:52:04)