Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments

Revision 2 as of 2009-01-21 14:51:20

Clear message

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

Suppose you want to make a bugfix in a project that is kept in bzr. Here's an overview of how you'd do it:

  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 [:Scenarios/ReviewIncorporate:this one])

  7. Maybe make some more commits, in response to the feedback
  8. Submit a new bundle.
  9. Lather, rinse, repeat until the change is accepted.

(Note that this recipe is designed to leave the door open to doing more work in the same project.)

Now let's look at the specific bzr commands. Let's say 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 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 echo "public_branch =" >> .bzr/branch/config bzr bind 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

...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 ...(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 ...(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 ../ 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 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 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 ...(edit yet more source files, until you reach a stopping point)... bzr commit -F another-log-message.txt cd ..

And send them again:

  • cd 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

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

  • bzr branch

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