Creating branches

For this section of the reviewers guide, you can actually create and publish a branch or two if you'd like. You'll need Bzr installed, and to have SSH keys which you can give to Launchpad to authenticate yourself. Alternatively, just read over the text to get a sense of what's possible.

If you want to try out the examples here then you will need to have Bazaar (bzr) installed on your machine. For Ubuntu users, just type "sudo apt-get install bzr" and you will be all set. For users of other platforms, take a look at [http://bazaar-vcs.org/Download: these instructions] to install Bzr for yourself.

You should have at least version 0.15 of Bzr installed:

• % bzr version
  Bazaar (bzr) 0.15.0candidate2

Now, let's branch the famous "GNU Hello" application, which is used as a demonstration of several GNU best practices and technologies. Note, for simplicity we will use HTTP to fetch the code for this branch, but this is quite an inefficient protocol for this purpose so it takes a little longer than normal to fetch the code. You can also use the optimised smart server protocol, once you have setup some keys to access the Launchpad server securely. We use HTTP here because it can be done anonymously.

• % bzr branch http://launchpad.net/gnuhello
  Branched 191 revision(s).

Done! You now have your own branch of GNU Hello.

• % cd gnuhello
  % ls
  ABOUT-NLS   ChangeLog     COPYING  Makefile.am  README        tests
  AUTHORS     ChangeLog.O   doc      man          README-alpha  THANKS
  autogen.sh  configure.ac  gnulib   NEWS         README.dev    TODO
  build-aux   contrib       INSTALL  po           src

You can see the latest commits on this branch (this is a branch of the trunk, so it has all the latest commits that trunk had when it was branched.

• % bzr log | head --lines=13
  ------------------------------------------------------------
  revno: 191
  committer: karl
  timestamp: Tue 2007-02-13 23:09:30 +0000
  message:
    .
  ------------------------------------------------------------
  revno: 190
  committer: karl
  timestamp: Mon 2007-01-22 14:40:04 +0000
  message:
    update from texinfo
  ------------------------------------------------------------

Because this is YOUR branch, you can commit to it immediately. Try making some changes and typing "bzr commit". Before doing this, you might want to configure Bazaar so that it knows who you are, and records that information with each commit. Type "bzr whoami 'Joe Smith <email@domain.com>'" to set that up.

Publishing branches

If you have [https://launchpad.net/people/+me/+editsshkeys:given Launchpad some SSH keys for yourself] then you can publish your branch with a single command. You need to know the project name in Launchpad, and your own username, and of course the name you want to give this branch. If your branch is just a personal one, that should not show up for a specific project, you can call it "junk" and use +junk instead of the project name.

Continuing our example above, we will push this GNU Hello branch to Launchpad with the command:

• % bzr push sftp://<me>@bazaar.launchpad.net/~<me>/gnuhello/mine

Of course, you must substitute your Launchpad username for <me> in both places in the above command.

Now, if you take a look at your own branch listing page, you will see the GNU Hello branch listed:

• https://code.launchpad.net/people/+me

As you can see, branching from an existing project, and publishing your branch, are extremely easy. Once your branch is published it is easy for others to find. If you would like your code to be included in the project's official line of development (and hence in the next release!) you can simply ask the project maintainers to review and merge your branch.

It may seem strange that you need your account name TWICE in the publishing command given above. The reason is that the first time (account@...) is to tell Launchpad who you are logging in as. The second time (~account/) is to tell it to put the branch into *your* directory. This is needed because you can also publish branches into directories for each of the teams in which you are a member. And that leads us to the next stop on our tour - [:ReviewersGuide/TeamBranches:Team Branches]!