How to check out EPICS Base with Bazaar

Bazaar can work with several different approaches; the one you should use depends on what you expect to do with the code-base. It usually allows you to change your mind later though, so don't worry if you pick the wrong model to start with, you can usually modify your configuration as you need later on (although I'm not going to give instructions on how to do that here).

You must have Bazaar version 2.x installed; older versions do not support the same repository format. I'm using version 2.0.1 at the time of writing this, but newer releases in the 2.x series should be fine.

Bazaar has extensive built-in help text, just type 'bzr help <command>' for more information on <command> or 'bzr help topics' for a list of other help topics. The complete documentation for the tool can be found online here.

Check out a working tree (for users, CVS model)

Use this option if you just want to a copy of the latest version of Base from the repository (for example to build and test) but don't expect to modify the code yourself or look at the history much. This approach is very similar to using CVS since you only download a copy of the particular revision you're interested in, but it does slow down all activities that need to access the repository in any way. An R3.14 working tree needs about 12MB of disk space at the time of writing.

The following command will create a directory tree called base-3.14 containing the latest code that was checked in to the 3.14 branch of Base:

  bzr checkout --lightweight lp:~epics-core/epics-base/B3.14 base-3.14

The B3.14 part in the above lp: path is the branch that you want to check out. B3.14 is a branch containing all the development work for the R3.14 releases of Base. There are other branches; B3.13 contains the R3.13 releases, and B3.12 the R3.12 releases (not that I'm expecting anyone to check either of these out, they're provided for historical reasons).

If you want to check out a particular tagged version, use this command instead:

  bzr checkout --lightweight -r tag:R3.14.11 lp:~epics-core/epics-base/B3.14 base-3.14

You can use 'bzr tags' from inside the working tree to list the tags known on this branch.

To update a lightweight working tree at a later date with the latest changes from the branch, use this command inside the tree:

  bzr update

If you made any local changes to the files in the tree your changes will be retained. Any that conflict with changes from the repository will have to be resolved by hand, just as with CVS.

Note that unlike with CVS, 'bzr update' cannot move your tree to a different historical revision, for that you use this command:

  bzr revert -r tag:R3.14.10

If you find yourself wanting to use 'bzr revert' more than once or twice, you should probably check out a branch instead, which creates a local copy of the complete history of the branch and removes the need for network activity when using that command.

Check out a branch (for users, local history)

This option is similar to the previous one but it also gives you a local copy of the complete history of the branch. This speeds up all activities that need to examine the repository history. This local branch is still bound to the central repository at launchpad.net though, so you can't commit any changes to it without write permission for the repository branch. The B3.14 branch needs about 28MB of disk space at the time of writing.

The following command will create a directory tree called base-3.14 containing the latest code and all of the history that was checked in to the 3.14 branch of Base:

  bzr checkout lp:~epics-core/epics-base/B3.14 base-3.14

The B3.14 part in the above lp: path is the branch that you want to check out. B3.14 is a branch containing all the development work for the R3.14 releases of Base. There are other branches; B3.13 contains the R3.13 releases, and B3.12 the R3.12 releases (not that I'm expecting anyone to check either of these out, they're provided for historical reasons).

If you want to check out a particular tagged version, use this command instead:

  bzr checkout -r tag:R3.14.11 lp:~epics-core/epics-base/B3.14 base-3.14

You can use 'bzr tags' when inside the working tree to list the tags known on this branch.

To update a lightweight working tree at a later date with the latest changes from the branch, use this command inside the tree:

  bzr update

If you made any local changes to the files in the tree your changes will be retained. Any that conflict with changes from the repository will have to be resolved by hand, just as with CVS.

Note that 'bzr update' cannot move your tree to a different historical revision, for that you use this command:

  bzr revert -r tag:R3.14.10

Check out a development branch (for developers)

Developers have a more complex configuration since they usually want to be able to commit their changes to a local repository and later on merge those changes into the branch in the central repository. The model described here corresponds to the "decentralized with shared mainline" workflow given in the Bazaar User Guide.

First initialize a local repository in a parent directory which will be used as the backing-store to hold the history of all your development work on EPICS Base, then inside this directory checkout a mirror branch of Base from Launchpad:

  bzr init-repo ~/epics-base
  cd ~/epics-base
  bzr checkout lp:~epics-core/epics-base/B3.14 mirror-B3.14

This mirror branch should never be used for code development. Work on developing new features or fixing bugs should take place in a different tree usually called a feature or task branch. The mirror branch exists to allow you to merge a tested set of changes from a feature branch into the central repository.

Bazaar encourages developers to create a separate branch for each separate feature or bug fix being developed, which would normally be created as a sibling to the mirror branch we checked out above. While working on the fix you are free to commit changes whenever you like, which are recorded in your local repository:

  cd ~/epics-base
  bzr branch mirror-B3.14 fix-123
  cd fix-123
  # Hack...
  bzr ci -m 'Fixing bug 123'

While you're working other developers may be committing changes to the central branch. To incorporate those changes is a two-stage process: First update your mirror branch to fetch those changes from the central repository, then merge and commit them into your working tree(s) as follows:

  cd ~/epics-base
  bzr update mirror-B3.14
  cd fix-123
  bzr merge
  # Resolve any conflicts...
  bzr ci -m 'Merged with B3.14'

The ability to commit changes to the central repository is restricted to members of the epics-core team at Launchpad.net, but Bazaar and Launchpad will still allow you to publish branches containing your own development even if you do not belong to that team; a team-member can subsequently merge and commit the changes from your branch into the official one.

For epics-core members, a feature branch is merged and committed to the central branch as follows:

  cd ~/epics-base/mirror-B3.14
  bzr update
  bzr merge ../fix-123
  # Resolve any conflicts...
  bzr ci -m 'Fixed bug #123'

If you're not a member of epics-core, you can publish your own branch on Launchpad that is linked to the epics-base project. You must have registered for an account at Launchpad.net first and uploaded your ssh public-key.

  bzr launchpad-login userid
  cd ~/epics-base/fix-123
  bzr push lp:~userid/epics-base/fix-123