Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments

Revision 10 as of 2009-01-22 05:19:49

Clear message

Making repeated contributions to a project in bzr.

[DRAFT: this page is still being reviewed by bzr experts for correctness.]

Suppose you want to make a bugfix in a project that is kept in bzr, and you think it's likely that you'll be making more contributions after this one is done. Here's an overview of how you'd go about this:

  1. Create a bzr repository, to store your branches related to this project
  2. Create a mirror "trunk" branch
  3. Create the task branch
  4. Do your work on the task branch, committing locally as you go
  5. When your changes are ready, package them up and submit them as a single "bundle" to the project
  6. Receive feedback (the reviewers are probably using a process like this one)
  7. Maybe make some more commits, in response to the feedback
  8. Submit a new bundle.
  10. Remove the old task branch.
  11. Create a new task branch for your next change.
  12. Do your work on the new task branch, etc, etc.

(This recipe differs from the one-off scenario in that this one is designed to make it easy to continue working in the same project after your first contribution is done.)

Let's look at the specific bzr commands. Assume the project's master bzr branch is located here:


First, initialize a repository in which to store your branches:

mkdir qproject
bzr init-repo qproject

Now create a local branch that will just be a mirror of the mainline (we'll never make any changes to this branch; its job is just to reflect the upstream master):

cd qproject
bzr branch http://qproject.org/bzr/qproject.dev/ qproject.dev-trunk
cd ..

Let's safeguard that local trunk, so you don't accidentally make any local changes on it (all your work will be done on a different branch, which we'll create in a moment). To safeguard, we "bind" the local branch to the upstream master branch:

cd qproject.dev-trunk
echo "public_branch = http://qproject.org/bzr/qproject.dev" >> .bzr/branch/config
bzr bind http://qproject.org/bzr/qproject.dev/
cd ..

Next, create the task branch on which you'll actually do your work. It will be based on the local trunk mirror we just created (another way to say it is that the task branch will be "branched from" the mirror):

bzr branch qproject.dev-trunk qproject.dev-NUMBER

...where "NUMBER" is, e.g., the bug tracker ticket number of the bug you're trying to fix, or if there is no ticket, then just make a short descriptive name for the bug.

At this point, you're ready to do work:

cd qproject.dev-NUMBER
...(edit source files until you reach a stopping point)...
bzr commit -F log-message.txt
cd ..

this assumes that the file ''log-message.txt'' contains a brief technical description of the changes you're committing; this is known as a "log message" or "commit message". You can also do bzr commit -m "blah blah blah", if your log message is short enough to fit on one line

Keep working, if the bug isn't fixed yet:

cd qproject.dev-NUMBER
...(edit yet more source files, until you reach a stopping point)...
bzr commit -F another-log-message.txt
cd ..

etc, etc. You can commit whenever you reach a good checkpoint. These commits just go to your local task branch. They don't affect the upstream master branch, and they don't even affect your local trunk mirror either.

By the way, from time to time you should refresh that local trunk mirror, by pulling in changes from upstream:

cd ../qproject.dev-trunk
bzr pull
cd ..

And after refreshing the local trunk mirror, you'll want to get those changes into your task branch, by merging them:

cd qproject.dev-NUMBER
bzr merge
bzr commit -m "Merge from mainline."
cd ..

The reason you use "merge" instead of "pull" in the task branch is that your task branch has local changes -- it has diverged (a bit) from the upstream master, and so any changes from upstream have to be merged with your changes. A "pull", on the other hand, assumes that the destination is pristine, that is, that there are no local changes, and will error if it finds any.

Once your bugfix is ready, create a "bundle" (that is, a file containing your change, in a special format that bzr understands but that is also human-readable):

cd qproject.dev-NUMBER
bzr send -o myfix-NUMBER.txt
cd ..

Now compose a mail to the project's mailing list describing the change; attach ''myfix-NUMBER.txt'' to that mail.

If the reviewers ask for further changes, just make them in the task branch:

cd qproject.dev-NUMBER
bzr commit -F another-log-message.txt
cd ..

And send them again:

cd qproject.dev-NUMBER
bzr send -o myfix-NUMBER.txt
cd ..

...until the changes are incorporated into the upstream. At this point, you can delete your task branch:

rm -rf qproject.dev-NUMBER

When you decide to work on the next bugfix, create a new task branch:

bzr branch qproject.dev-trunk qproject.dev-NEW_NUMBER

...and you know what to do from here.