As a casual contributor, fix a single bug in a project already 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 it's unlikely you'll do any further work on this project. Here's an overview of how you'd go about this:
- Create a branch from the project's trunk for developing your bugfix
- Do your work on the branch, committing locally as you go
- When your changes are ready, package them up and submit them as a single "bundle" to the project
- Receive feedback (the reviewers are probably using a process like this one)
- Maybe make some more commits, in response to the feedback
- Submit a new bundle
- Lather, rinse, repeat until the change is accepted.
- Remove the now-unnecessary bugfix branch.
(This recipe differs from the repeated contributions scenario, which is designed to make it easy to continue working in the same project after you've made your first contribution.)
Let's look at the specific bzr commands. Assume the project's master bzr branch is located here:
First, we create a branch of the project's mainline; we'll call this your task branch. (The mainline is often referred to as the upstream master branch.) The task branch will be "branched from" the mainline:
bzr branch http://qproject.org/bzr/qproject.dev/ 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 a short descriptive name for the bug.
Note: creating a branch normally downloads the entire history of that branch; this is a feature of distributed version control systems. If you are low on disk-space or are behind a slow network, and are certain that you will not need the past revision history, you may want to use a stacked branch; see below for more details about stacked branches.
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
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. Or simply bzr commit to have bzr prompt for a commit message using your current editor.
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
etc, etc. You can commit whenever you reach a good checkpoint. These commits are local to your branch. They don't affect the upstream master branch; in fact, nobody else sees them happening.
Once your bugfix is ready, create a "merge directive" (that is, a file containing your change, in a special format that bzr understands but that is also human-readable):
bzr send -o myfix-NUMBER.txt
Now compose an e-mail to the project's mailing list describing the change and attach ''myfix-NUMBER.txt'' to that message. (Here's an example.)
Note: bzr can be configured to invoke your mailer directly to create a message with the merge directive attached. See the user reference for details on configuring bzr's mail_client parameter for your mailer.
If the reviewers ask for further changes, just make them in the task branch and send them again:
cd qproject.dev-NUMBER ...(edit yet more source files, until you reach a stopping point)... bzr commit -F another-log-message.txt bzr send -o myfix-NUMBER.txt
...until the changes are incorporated into the upstream. At this point, you can delete your task branch:
rm -rf qproject.dev-NUMBER
Saving Space Using Stacked Branches
In Step 1, we branched from qproject's trunk, pulling the entire history of the trunk. There are some situations where you may not need this entire history. Bzr's stacked branches, new to bzr 1.9, may be of help. A stacked branch depends on another branch, which may be a remote branch, for finding earlier revisions. You create a stacked branch by adding the --stacked parameter to the branch command:
bzr branch --stacked http://qproject.org/bzr/qproject.dev/ qproject.bugfix
This command effectively pulls only the latest revision from the source branch, and notes that any history-referencing operations must refer to the source branch.
Stacked branches involve a trade-off between saving disk space and incurring network delay. Although the full history is not downloaded, any operation requiring history, such as log or diff to an earlier revision, requires accessing the source branch. In the case above, such operations will require network access. See the user guide for more details.