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-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), and the branch called trunk will eventually become B3.15.

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-core/epics-base/B3.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 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

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-core/epics-base/B3.14 mirror-B3.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-B3.14 fix-123
  cd fix-123
  # Hack...
  bzr ci -m 'Fixing bug 123'

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-B3.14
  # For each task branch:
  cd fix-123
  bzr merge
  # If conflicts reported, resolve them and tell bzr
  bzr resolve file
  # Commit the merge
  bzr ci -m 'Merged with B3.14'

Merges: Committing

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'

To apply a series of bug-fix changes to more than one branch series, say to both 3.14 and the main trunk,

TEXT INCOMPLETE...

Publishing a Private 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:~userid/epics-base/fix-123