Bazaar

Bazaar

 




Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments

Differences between revisions 4 and 5
Revision 4 as of 2009-01-21 14:54:48
Size: 4975
Editor: Karl Fogel
Comment: Shorten draft notice.
Revision 5 as of 2009-01-21 15:30:38
Size: 4941
Editor: JohnMeinel
Comment: Change formatting to ReStructured Text
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
''[DRAFT: this page is still being reviewed by bzr experts for correctness.]'' #FORMAT rst
===============
Bugfix Scenario
===============

*
[DRAFT: this page is still being reviewed by bzr experts for correctness.]*
Line 5: Line 10:
 1. Create a bzr repository, to store your branches related to this project
 1. Create a mirror "trunk" branch
 1. Create the task branch
 1. Do your work on the task branch, committing locally as you go
 1. When your changes are ready, package them up and submit them as a single "bundle" to the project
 1. Receive feedback (the reviewers are probably using a process like [:Scenarios/ReviewIncorporate:this one])
 1. Maybe make some more commits, in response to the feedback
 1. Submit a new bundle.
 1. Lather, rinse, repeat until the change is accepted.
#. Create a bzr repository, to store your branches related to this project
#. Create a mirror "trunk" branch
#. Create the task branch
#. Do your work on the task 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 [:Scenarios/ReviewIncorporate:this one])
#. Maybe make some more commits, in response to the feedback
#. Submit a new bundle.
#. Lather, rinse, repeat until the change is accepted.
Line 17: Line 22:
Now let's look at the specific bzr commands. Let's say the project's master bzr branch is located here: Now let's look at the specific bzr commands. Let's say the project's master bzr branch is located here::
Line 19: Line 24:
{{{
http://qproject.org/bzr/qproject.dev/
}}}
  http://qproject.org/bzr/qproject.dev/
Line 23: Line 26:
First, initialize a repository in which to store your branches: First, initialize a repository in which to store your branches::
Line 25: Line 28:
{{{
mkdir qproject
 bzr init-repo qproject
}}}
  mkdir qproject
  bzr init-repo qproject
Line 30: Line 31:
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): 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)::
Line 32: Line 33:
{{{
cd qproject
 bzr branch http://qproject.org/bzr/qproject.dev/ qproject.dev-trunk
 cd ..
}}}
  cd qproject
  bzr branch http://qproject.org/bzr/qproject.dev/ qproject.dev-trunk
  cd ..
Line 38: Line 37:
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: 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::
Line 40: Line 39:
{{{
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 ..
}}}
  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 ..
Line 47: Line 44:
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): 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)::
Line 49: Line 46:
{{{
bzr branch qproject.dev-trunk qproject.dev-NUMBER
}}}
  bzr branch qproject.dev-trunk qproject.dev-NUMBER
Line 55: Line 50:
At this point, you're ready to do work: At this point, you're ready to do work::
Line 57: Line 52:
{{{
cd qproject.dev-NUMBER
 ...(edit source files until you reach a stopping point)...
 bzr commit -F log-message.txt
 cd ..
}}}
  cd qproject.dev-NUMBER
  ...(edit source files until you reach a stopping point)...
  bzr commit -F log-message.txt
  cd ..
Line 64: Line 57:
  his 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 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
Line 66: Line 59:
Keep working, if the bug isn't fixed yet: Keep working, if the bug isn't fixed yet::
Line 68: Line 61:
{{{
cd qproject.dev-NUMBER
 ...(edit yet more source files, until you reach a stopping point)...
 bzr commit -F another-log-message.txt
 cd ..
}}}
  cd qproject.dev-NUMBER
  ...(edit yet more source files, until you reach a stopping point)...
  bzr commit -F another-log-message.txt
  cd ..
Line 78: Line 69:
mirror, by pulling in changes from upstream: mirror, by pulling in changes from upstream::
Line 80: Line 71:
{{{
cd ../qproject.dev-trunk
 bzr pull
 cd ..
}}}
  cd ../qproject.dev-trunk
  bzr pull
  cd ..
Line 86: Line 75:
And after refreshing the local trunk mirror, you'll want to get those changes into your task branch, by merging them: And after refreshing the local trunk mirror, you'll want to get those changes into your task branch, by merging them::
Line 88: Line 77:
{{{
cd qproject.dev-NUMBER
 bzr merge
 bzr commit -m "Merge from mainline."
 cd ..
}}}
  cd qproject.dev-NUMBER
  bzr merge
  bzr commit -m "Merge from mainline."
  cd ..
Line 97: Line 84:
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): 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)::
Line 99: Line 86:
{{{
cd qproject.dev-NUMBER
 bzr send -o myfix-NUMBER.txt
 cd ..
}}}
  cd qproject.dev-NUMBER
  bzr send -o myfix-NUMBER.txt
  cd ..
Line 107: Line 92:
If the reviewers ask for further changes, just make them in the task branch: If the reviewers ask for further changes, just make them in the task branch::
Line 109: Line 94:
{{{
cd qproject.dev-NUMBER
 ...(edit yet more source files, until you reach a stopping point)...
 bzr commit -F another-log-message.txt
 cd ..
}}}
  cd qproject.dev-NUMBER
  ...(edit yet more source files, until you reach a stopping point)...
  bzr commit -F another-log-message.txt
  cd ..
Line 116: Line 99:
And send them again: And send them again::
Line 118: Line 101:
{{{
cd qproject.dev-NUMBER
 bzr send -o myfix-NUMBER.txt
 cd ..
}}}
  cd qproject.dev-NUMBER
  bzr send -o myfix-NUMBER.txt
  cd ..
Line 124: Line 105:
...until the changes are incorporated into the upstream. At this point, you can delete your task branch: ...until the changes are incorporated into the upstream. At this point, you can delete your task branch::
Line 126: Line 107:
{{{
rm -rf qproject.dev-NUMBER
}}}
  rm -rf qproject.dev-NUMBER
Line 130: Line 109:
When you decide to work on the next bugfix, create a new task branch: When you decide to work on the next bugfix, create a new task branch::
Line 132: Line 111:
{{{
bzr branch qproject.dev-trunk qproject.dev-NEW_NUMBER
}}}
  bzr branch qproject.dev-trunk qproject.dev-NEW_NUMBER

Bugfix Scenario

[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. 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:

http://qproject.org/bzr/qproject.dev/

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

System Message: WARNING/2 (<string>, line 56); backlink

Inline interpreted text or phrase reference start-string without end-string.

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
...(edit yet more source files, until you reach a stopping point)...
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.