Skip to Navigation | Skip to Content

Project Administration

Overview

This section describes tasks that are generally done by the project leader, in order to properly control repository branching, tagging and so on, thus ensuring that all strands of activity in a project integrate smoothly.

Making a tag

A "tag" is made in Subversion when you want to officially declare a release, i.e. publish a certain set of deliverables under the name of the tag. Practically speaking, this means telling the Subversion repository that a certain version (usually the latest, but can be any) of the mainline of development (found in the TRUNK) is to be known by a label (e.g. something like "Release-1.1", or "panther"....).

To do this in Subversion, you are really telling it to do a copy of one URL (http://svn.openEHR.org/some_repo/TRUNK) to some new URL in the TAGS subdirectory of the repository (the URL will be http://www.openEHR.org/svn/some_repo/TAGS/my_new_tag). Subversion knows about this kind of copying, and makes a "lazy" copy - it doesn't actually copy the files to the new URL. However if you as a user do a new update of the entire repository (i.e. http://www.openEHR.org/svn/some_repo) you will get an entire copy of those files under the directory some_repo/TAGS/my_new_tag. Normally you wouldn't bother doing this, since you are not going to change the files in the tagged area (however, there is nothing to prevent you doing this, and if you saw some awful error, e.g. in web pages in the release, you might reasonably go and make a change to the relevant files in the TAGS/my_new_tag area, and commit the changes as normal).

Procedure in TortoiseSVN

  • right click on a directory inthe Explorer; usually you should be on the TRUNK directory
  • choose TortoiseSVN > Branch/Tag
  • make sure the surce URL is http://www.openEHR.org/svn/some_repo/TRUNK; you can choose either the latest or an earlier revision to tag
  • make sure the target URL looks like http://www.openEHR.org/svn/some_repo/TAGS/my_new_tag
  • put in a comment message indicating the tag and why
  • commit the changes.

Nothing much will seem to happen, this is because it is all happening on the server. Don't worry, if it doesn't work TortoiseSVN will tell you. You can verify that it has worked by putting the new URL into a browser (use the wsvn variant if you want) and see if you can now browse the tagged version. For example, try putting http://www.openehr.org/svn/specification/TAGS/Release-1.0.2/publishing/index.html into a browser: you will see the tag copy of openEHR 1.0.2 specifications.

Making a Branch

Mechanically speaking, the branch operation is the same in Subversion as the tag operation - it is a smart copy of the current (or previous) version of the TRUNK into the BRANCHES directory. The only difference is that with a branch, the intention is that someone will start to modify the contents; at some later point, the changes made by this person can be merged back into the mainline of development.

The main challenge is knowing when to do a branch. The usual reasons is that you have or intend to have multiple releases in your repository, and you have to support more than one of them in parallel. For example, you have Release-1.0 of some java code, and it is deployed somewhere. Clearly, the development team cannot just forget about this code if it is being used. Therefore, it needs to be maintained - i.e. have bugs fixed, and tested. However, the development team is undoubtedly building a better version of the code, to be called Release-1.1 (or anything it likes; numeric identifiers might be boring, but at least it is obvious which order the releases come in!). To start work on Release 1.1, there are two strategies.

Branching Strategy #1

In this strategy, multiple releases can be maintained in parallel. This is the normal strategy for software development. The TRUNK is considered the latest work - all the new exciting stuff gets done there. At certain points in the life of the TRUNK, branches are made, each corresponding to a named release. The procedure is nearly the same as for declaring a tag above, i.e.:

  • in the Explorer right click on the directory containing the 'source' code; usually you will be on the TRUNK directory
  • choose TortoiseSVN > Branch/Tag
  • make sure the surce URL is http://www.openEHR.org/svn/some_repo/TRUNK; you can choose either the latest or an earlier revision to tag
  • make sure the target URL looks like http://www.openEHR.org/svn/ some_repo/BRANCHES/your_new_branch  # use 'Release-x.y' for releases in the TAGS or RELEASES areas
  • put in a comment message indicating the branch and why
  • commit the changes.

The result of this is that on the server a smart copy of the current state of the TRUNK now exists in BRANCHES/your_new_branch (or TAGS/Release-x.y). Developers working on that release should then check the new branch URL of the repository out, and work on that, only making changes that should be in the release. As soon as the release is declared, it should be tagged, and the changes to the branch area should be limited to bug fixes. Multiple tags might be done from this release over its like, usually all corresponding to minor versions, e.g. from Release 1.1, you might tag 1.1.1, maybe 1.1.3, 1.1.4 and so on. Tags are only required where the need for that exact version of the software to be rebuilt exists (e.g. by some customer).

The developers working on new features will continue working on the TRUNK, until they decide they are close to another release; then they will repeat the same thing all over again.

Bugs that are fixed in the branch releases can be merged into the TRUNK using the TortoiseSVN & TortoiseMerge tools.

When there are no users of an older release, work will normally cease on that branch.

Branching Strategy #2

In this strategy, releases are created and no further changes are made to them. Work only occurs on the latest version of the repository. This strategy is suitable for specfication or documentation projects, like the openEHR specification project. It works as follows. Developers are working in the mainline (i.e. the TRUNK); when the deliverables are close to being released, a release candidate branch is declared. So instead of the branch being http://www.openEHR.org/svn/some_repo/BRANCHES/Release-x.y as in strategy #1 above, it will be http://www.openEHR.org/svn/some_repo/BRANCHES/Release-x.y-candidate. Work then continues in the branch release candidate area, until the deliverables are ready for release. When they are ready, the candidate area contents are merged into the mainline, overwriting them (there are various ways to do this; export and local copy is easy). The mainline is now brought up to date to this release. A tag would then be declared for the release. 

Work will now continue on the mainline, or a new release candidate branch could immediately be declared, and the process repeated. The whole process could of course be done with no branches at all - just by working continually on the TRUNK and making tags when necessary. However, in reality, it is useful to have named release candidate branches, since it makes navigation in the Subversion repository more obvious, and it also allows current releases to exist for a while on the TRUNK before they are tagged officially, in order to have time to correct typographical errors in documents and so on.

Comments (0)