wiki:pm-svn-releases

Version 2 (modified by andreasw, 14 years ago) (diff)

first version

Suggested Way to Handle Releases

This page describes how the policy for releases suggested by COIN can be maintianed with subversion. You might want to first read the page on understanding branches and tags, or other pages for understanding subversion. Below, the string YourProject? is to be repleaced by the name of your project.


One-Time Steps

First you want to make sure that the directories trunk, stable, and releases exist for your project. An easy way to do this is to load the webpage https://projects.coin-or.org/svn/YourProject (such as https://projects.coin-or.org/svn/BuildTools). This lists the base directories in your project.

If a directory, say releases, does not yet exist, you can create it directly in the svn repository with the svn mkdir command, giving it the full URL. For example:

svn mkdir https://projects.coin-or.org/svn/YourProject/releases \
           -m "creating releases directory"

stable Branchs

The idea of a stable branch is that you maintain a stable line of your code here, that can be used by a user who wants to be up-to-date with your "official" version of the code. You start with a version that you think is good enough to be made "official". Later, you update the code in a particular stable branch, for example to include bug fixes, or because you add some improvements. Typically, when you fixed a bug reported by a user, you would fix it in the corresonding stable release, and tell the user how to get it. When it seems to work, you should probably make a new release (see below).

Note: We strongly suggest to create a new stable branch when the user interface for your code changes in a way, so that users of your code would have to change their code in order to use the new code. By creating a new stable branch, a user will not find any bad surprises when updating his/her local copy of a stable branch, and can instead switch to a new stable branch later, whenever (s)he is ready.

Creating a new stable branch

You usually create a new stable branch, with a version number x,y, say 2.3, from some version of your code that exists in the repository. Typically, you would have been working in trunk (where the active development takes place), and want to releases the current trunk version in the repository as a new stable branch.

A new stable branch with the chosen version number is create in the repository, using the svn copy command. In order to create stable branch 2.3 from trunk you could use

svn copy https://projects.coin-or.org/svn/YourProject/trunk \
           https://projects.coin-or.org/svn/YourProject/stable/2.3 \
           -m "Creating new stable branch 2.3 from trunk (rev 533)"

NOTE: In the commit message you should always record the subversion revision number from which you created the new branch. This information is essential for merging and some other repository operations. To find out the revision number, you can use the svn info command. For example, to determine the revision number in the above example, you could have used

svn info https://projects.coin-or.org/svn/YourProject/trunk

and looked at the line that starts with "Revision:".

Updating the stable branch

To change the content for a stable branch you work with it as usually: creating a local copy of the code in that branch, making changes there (directly by editing, or by using svn merge to include changes made in a different version in the repository, such as trunk), and finally submitting the changes back to the repository.


The release tags

The release directory is the place where a user can find particular, numbered releases. The tarballs distributed on the COIN-OR website are created from those releases. It is mandatory that by checking out a release from this place in the repository always proves the identical code, so that restore older versions is possible (for example for reproducing bugs). In this context you need to be careful if you use svn:externals. Once a release has been created it must not be changed'''

Creating a new release

Typically, you would have a version of your code in a stable branch, say 2.3, which you now want to make an official release.

If you are using Externals: Before creating the new releaes from the current version in the stable branch, you need to make sure that all svn:externals are pointing to releases of the dependencies so that your release can be recreated exactly at any point in time, even if the development of the dependencies progressed. So, please make sure that all URLs in your Externals file are pointing to something in the release directory of the dependencies. Also, make sure that the externals are indeed set according to the file content (verify with svn pget svn:externals https://projects.coin-or.org/svn/YourProject/stable/2.3).

To create a new release, say 2.3.6, you use the svn copy command:

svn copy https://projects.coin-or.org/svn/YourProject/stable/2.3 \
           https://projects.coin-or.org/svn/YourProject/releases/2.3.8 \
           -m "Creating new release 2.3.8 from stable/2.3 (rev 567)"

Again, it is a very good idea to log the subversion repository revision number in the commit message.