bzr-doc team mailing list archive

[Neil Martinsen-Burrell <nmb@xxxxxxxxxxxx>]

I had a go at a handful of doc bugs this weekend and I've got some 
thoughts for people who want to get involved for the first time.

1.  Just try it!  The first patch you submit will seem like the biggest. 
 If necessary, pick one with a simple one sentence change to get your 
toes wet.  There are a couple of broken links in that list that could be 
good starting places.

2.  Choose something you know, or if you don't know then experiment.  In 
trying to fix a bug with missing documentation about tag conflicts, I 
had to try some things to reproduce the message from the bug report. 
``bzr ci -m 'test' --uncommitted`` can be your friend.  Go ahead and 
make a branch ``bzr init ~/tmp/trunk``, add a single file ``touch 
~/tmp/trunk/a; bzr add ~/tmp/trunk; bzr ci -m 'first' ~/tmp/trunk`` and 
branch it ``bzr branch ~/tmp/trunk ~/tmp/branch``.  This setup got me 
where I needed to go.

3.  Make sure to do your fix in a separate branch.  I accidentally 
committed one of my fixes directly to my local mirror of bzr.dev and it 
polluted the rest of the fixes that I based on my local bzr.dev.  Oops. 
 My personal style is

$ bzr init-repo ~/bzr
$ cd ~/bzr
$ bzr branch lp:bzr bzr.dev
$ bzr branch bzr.dev fix-1234567
$ cd fix-1234567 # hack, hack, hack

Then when you're done, you can

$ bzr ci -m 'add more accurate documentation' --fixes lp:1234567
$ bzr push lp:~your_lp_username/bzr/fix-1234567
$ bzr lp-open

and from the resulting web page you can propose your branch for merging 
into bzr.  Different people have different organizational strategies 
that work for them.

4.  For fixing many bugs in a short period of time, it can be nice to 
use a lightweight checkout as the working copy and ``bzr switch -b 
new_branch`` to switch quickly between different tasks.  Here's what I 
ended up with:

$ bzr co --lightweight bzr.dev work
$ cd work # hack, hack, hack
$ bzr switch --create-branch ../fix-1234567 # don't commit before this
$ bzr ci -m 'add more accurate documentation' --fixes lp:1234567
$ bzr push lp:~your_lp_username/bzr/fix-1234567; bzr lp-open
$ bzr switch bzr.dev  # don't forget this before starting the next bug

Then, you can start working again and ``bzr switch --create-branch ...`` 
again when you've got something to commit.  Also, remember that from the 
work directory, ./bzr will let you see the effect of your changes. 
Again, some people like this organizational strategy all of the time, 
but do whatever works for you.

5.  For some of those bugs, there probably needs to be discussion about 
what the right way to fix them is.  I hope that this list will be an 
easier place to start those discussions than would the main bzr mailing 
list.

6.  Bazaar in particular makes these sorts of changes very easy.  Every 
time I go through this cycle from ``bzr branch ...`` to ``bzr lp-open`` 
I'm surprised at how easy it is.  I've never learned diff well enough to 
submit patches via email and now I won't need to.

-Neil