← Back to team overview

bzr-doc team mailing list archive

(Relative) newbie fixes some doc bugs: thoughts and experiences


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.


Follow ups