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 at all, or to look at its 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 require network connectivity for all activities that access the repository in any way. An EPICS Base 3.14 working tree uses 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-base/3.14 base-3.14

The lp: path above specifies a branch to check out from the launchpad server. The branch at lp:epics-base/3.14 is a branch containing all the development work for the R3.14 releases of Base. There are similar branches for the older series, although we're not expecting anyone to check any of these out; they're provided for historical reasons. The development on the branch called trunk will eventually become the 3.15 series.

If you want to check out a specific tagged version, in this case we're requesting the R3.14.11 release, use this command instead:

  bzr checkout --lightweight -r tag:R3.14.11 lp:epics-base/3.14 base-3.14

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

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

Unlike CVS, 'bzr update' cannot apply changes that move your tree to a different historical revision; for that you use the command below, in this case to move to the R3.14.10 release tag:

  bzr revert -r tag:R3.14.10

If you made any local changes to the files in the working tree your changes will be retained through a 'bzr update' or 'bzr revert' operation. Any local changes that overlap with changes from the repository will create a conflict and have to be resolved by hand, just as happens with CVS.

If you find yourself using Bazaar commands inside the tree more than once or twice, you should probably check out a branch instead, which makes a local copy of the complete history of the branch and removes the need for network activity to access that history.

Check out a branch (for users, local history)

This option is similar to the previous one but 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, but since the local branch is still bound to the central repository at launchpad.net you can't commit any changes to it without write permission for the repository branch. A 3.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-base/3.14 base-3.14

The lp: path above specifies a branch to check out from the launchpad server. The branch at lp:epics-base/3.14 is a branch containing all the development work for the R3.14 releases of Base. There are similar branches for the older series, although we're not expecting anyone to check any of these out; they're provided for historical reasons. The development on the branch called trunk will eventually become the 3.15 series.

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/3.14 base-3.14

Inside the working tree, Bazaar supports the expected commands 'bzr log' and 'bzr diff' to examine file history. Use 'bzr help revisionspec' for information on specifying particular revisions to examine.

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

  bzr update

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

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

If you made any local changes to the files in the working tree your changes will be retained through a 'bzr update' or 'bzr revert' operation. Any local changes that overlap with changes from the repository will create a conflict and have to be resolved by hand, just as happens with CVS.

If you want to keep some permanent local changes, consider unbinding your tree from the central repository branch, which converts it to a regular branch. This will allow you to check local changes into the local repository while still permitting 'bzr update' to fetch changes as before. The 'bzr unbind' command does this, and can be undone again with 'bzr bind'.

Developer Branches

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.

Initial Checkout

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-base/3.14 mirror-3.14

This mirror branch should never be used directly for developing new code or bug fixes. Work of this kind should take place in a different tree usually called a feature or task branch. The mirror branch exists to allow you to merge tested sets of changes from your feature branches into the central repository.

Creating a Task Branch

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-3.14 fix-123
  cd fix-123
  # Hack...
  bzr ci -m 'Hacked the frooz-bodger to stop it wibbling'

Merges: Updating

While you're working other developers may be committing changes to the central branch. To incorporate those changes into your task branches is a two-stage process: First update your mirror branch to fetch those changes from the central repository, then merge and commit them into each of your working trees. Note that you should probably check in any local modifications into the task branches before doing the merge step or the final commit command will do that for you, probably with the wrong log message:

  cd ~/epics-base
  bzr update mirror-3.14
  # For each task branch:
  cd fix-123
  bzr merge
  # Fix any conflicts and tell bzr like this:
  bzr resolve file
  # Finally commit the merge
  bzr ci -m 'Merged with 3.14'

Merges: Committing Changes

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-3.14
  bzr update
  bzr missing ../fix-123
  # Check that you're about to merge the right changes
  bzr merge ../fix-123
  # Fix any conflicts and tell bzr like this:
  bzr resolve file
  # Finally commit the merge
  bzr ci -m 'Fixed bug #123'

To apply a bug-fix change to more than one branch series, say to both 3.14 and the main trunk, Bazaar's merge command allows you to cherry-pick commits from a different branch. If it's just one check-in this is very easy, especially if it's the last commit you made to that source branch. In that case, you would use these commands to merge those changes to the trunk:

  cd ~/epics-base/mirror-trunk
  bzr update
  bzr merge -c -1 ../fix-123
  # Fix any conflicts and tell bzr like this:
  bzr resolve file
  # Finally commit the merge
  bzr ci -m 'Fixed bug #123'

The '-c -1' option to 'bzr merge' means "cherry-pick just the last commit", '-c -2' would be the penultimate commit and so on. You can use 'bzr log' in the feature branch to find a specific absolute revision number on that branch and use that instead of the negative numbers. If there were several commits you can give 'bzr merge' a range using the option '-r 44..47' instead, but note that '-r 44' means "merge all changes up to and including revision 44." If you get it wrong, you can always use 'bzr revert' to undo.

After you have merged and committed your changes from a feature branch into the central branch(es) at launchpad, you may delete the branch directory as necessary ('rm -rf fix-123').

Shelving Local Changes

If you have some local changes that you don't want to commit, say some CONFIG_SITE changes needed to build the code at your site, you can use 'bzr shelve configure/CONFIG_SITE' to temporarily hide them before committing or merging, and 'bzr unshelve' later to bring them back. The shelve command will show you each of the changes in the named file(s) in turn and ask whether you want to shelve it or not. Read the 'bzr help shelve' output for more details.

Publishing a Branch

If you're not a member of epics-core, you can still publish your own branches of the epics-base project on Launchpad where other people can find and use them. 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:~user-id/epics-base/fix-123

If you are a member of epics-core, you can create a shared branch that other members can also commit to by using the group name as the user-id in the Bazaar target path:

  bzr push lp:~epics-core/epics-base/feature-xyz