andymatuschak.org: Sparklings

I’ve got Sparkle 1.5b1 out, but unfortunately, I don’t have time to write the documentation or any of the supporting material at the moment.

This is kind of a problem.

So until I get a chance to do that, following is a brief guide on using Bazaar to contribute to Sparkle.

Getting the Source

First, you’ll have to get Bazaar. The easiest way to do that is to grab a .pkg from the project homepage. MacPorts is more trouble than you want to deal with.

Now, here’s all it takes to get a fresh copy of Sparkle’s code:

bzr branch lp:sparkle

Contributing to Sparkle

The main reason I switched to Bazaar is that it’s now so easy to contribute to Sparkle. And, thankfully, it’s just as easy for me to integrate your contributions.

There are just a few steps you’ve got to do the first time you’d like to contribute:

1. Grab a Launchpad account. Launchpad will host your branches; it also keeps track of which bug[s] your branch fixes.
2. Head over to your profile and click the link on the left to update your SSH keys. This is how you authenticate to Launchpad. If you don’t have a public key, it’ll explain how to generate one.
3. Let bzr know who you are. Open up a command prompt and run:

   bzr launchpad-login YOUR_LP_USERNAME

4. Then make sure you get credit for your work with:

   bzr whoami "Joe Henderson <theemailaddress@yougavelaunchpad.com>"

From here, the average lifecycle looks very much like SVN’s:

1. bzr pull to get the latest code.
2. Make whatever changes you’d like to make.
3. bzr add foo.c bar.h to tell Bazaar about any new files.
4. bzr commit -m "Description here" to record the patch, OR if you’re fixing a particular bug, run this to link the revision to the bug:

   bzr commit --fixes lp:12345 -m "Description here"

If you do that a bunch of times, you’ll have a number of patches on your computer, but they won’t be on the server yet. To publish your changes, you make a branch. Here’s how:

bzr push lp:~YOUR_LP_USERNAME/sparkle/BRANCH_NAME

That’s it! You’re done! Your code’s online, and if you linked revisions to bugs, your branch will show up on the bug description page.

You can explicitly propose your branch for merging into the main branch: just login, find the branch in question on your profile, and click the proposal link on the navigation bar.

If you want to keep working with your branch, just run this every so often to merge in any changes from the main branch:

bzr merge lp:sparkle

You can read more about Bazaar in the great user guide on its homepage. And if you run into trouble, feel free to ask a question.