1.3. Version management

At certain times to be defined by the project's administrators (actually configuration manager) a snapshot is taken from the repository. In order to fix the stage of this snapshot in the repository, a tag is placed on this stage. Tagging the repository creates a version of the project.

1.3.1. Layout of the version numbers

The version number is made out of three numeric fields. These are:

  1. The major release number

  2. The minor release number

  3. The micro release number

In order to serve as a tag for CVS, the text rel- is prepended to the version numbers and the three fields are seperated with a dash (e.g. rel-0-3-7).

The major release number will be changed when all the proposed features mentioned in the release plan (available on the project web-site) are designedi, coded and tested.

One of the objectives of the minor release number is to differentiate between stable and unstable versions of the project. As a widely accepted procedure, odd numbers are used for development versions, even numbers identify stable versions. Whenever the configuration manager decides that to create a new stable release, this will also bump the version number of the unstable release by two.

The micro release number is reset to 0 when the minor release number is incremented and then incremented with each version following until the minor release number is modified again. Versions tagged between the creation of a stable branch and the actual release -0 of this branch will be identified by a micro release number of pren, where n is incremented each time a version is tagged.

1.3.2. Creating a new version

At certain stages it is necessary to release a version as a tar-ball archive. As all releases must be reproducable, the contents of the tar-ball archive must be tagged in the repository. The following paragraphs explain what needs to be done in that case.

Note

The steps explained apply for both the development branches as well as the release branches. For convenience, the examples are based on the development branch.

  1. Make sure that the project version is set correct to the version to be created (e.g. 0.5.6). If this is not the case, change the version in KDevelop. This should regenerate a bunch of files automatically. Checkin the changes you have made to the repository before you proceed with the next step.

  2. Tag the version with the applicable tag (e.g. rel-0-5-6)

  3. Make sure that you increase the project version to the next version (e.g. 0.5.7). This again should regenerate a bunch of files automatically. Checkin the changes you have made to the repository before you proceed with the next step.

Note

The version number in the sandbox is always the version number that is currently developed (we're a little ahead here).

1.3.3. Creating a new stable version

At a certain time in the project's development cycle, the configuration manager decides that a feature freeze is necessary to start a new stable version. The exact dates when this will happen are announced on the developers mailing list ahead of the event. When the time has come to freeze the features, a branch will be created as described in this section. From this time on, the stable release will only be changed to make the current features of the software more stable. New features are not introduced to the stable branch but can be developed on the main branch (unstable) in parallel.

When the time has come to create a new stable branch, the following steps have to be performed.

  1. Make sure that the project version is set correct to the stable version to be created (e.g. 0.4.pre1). If this is not the case, change the version in KDevelop. This should regenerate a bunch of files automatically. Checkin the changes you have made to the repository before you proceed with the next step.

  2. Tag the currently unstable version with the root-name of the stable version. The root-name is identified by appending the text pre1 to the version number. For example, the root tag for versions 0.4 is rel-0-4-pre1.

  3. Create a branch off of this root. The branch name is build by appending the text -branch to the major- and minor-release number of the version. For our example, the branch tag for versions 0.4 is rel-0-4-branch. A complete example with all CVS commands can be found in the appendix.

  4. Change the project version to the next development version (e.g. 0.5.0). Change the version in KDevelop. This should regenerate a bunch of files automatically. Checkin the changes you have made to the repository before you proceed with the next step.

  5. Tag the the current version with the base-name of the next unstable release. The base name is constructed using the appendix -base to the major and minor release number of the next unstable version. In our example this will be rel-0-5-base.

    From this moment on, the developers working on versions 0.4.x must make sure, that they checkout or update their sandbox using the tag rel-0-4-branch. This gives them the head revisions of the files on the 0.4 branch. Omitting this tag information will leave them on the main branch. The main branch is reserved for the unstable versions. An example how to keep multiple branches on the same machine is presented in the appendix,

    Caution

    The developers really have to take care from this point on which version they are modifying in their sandbox. Besides that, it is the developers responsibility to make sure that bug-fixes are also implemented on the main-branch.

    When fixes are applied to the branch, new versions can be created by incrementing the micro-release thus rel-0-4-pre2, rel-0-4-pre3 are the next tags on the branch.

  6. When the configuration manager is confident with the development effort, he creates the first stable tag for the version. It is identified by a micro-release number of 0. For our example, the branch now contains a tag called rel-0-4-0.

Note

Since CVS does not allow periods inside a tag, we always replace periods (.) with dashes (-) inside a tag.

The following diagram shows the above example on two specifc files. Each node represented by an asterisk is labelled with it's revision number enclosed in parenthesis. If a node has one or more labels attached, then they are enclosed in brackets. Nodes may exist without a tag. Such revisions never went into a release neither stable nor unstable but are valid intermediate steps in the development of the file in question.

Example 1-1. Revisions on the head of a stable branch

The first file is changed rather often between the version tags. All tags are on different revision, except the ones required when the branch for the stable version is created on revision 1.14.


     *     (1.12) [rel-0-3-8]
     |
     *     (1.13)
     |
     *     (1.14) [rel-0-4-pre1] [rel-0-5-base]
     |\__________________________
     |                           \
     |                            |
     *     (1.15)                 * (1.14.2.1)  [rel-0-4-pre2]
     |                            |
     *     (1.16) [rel-0-5-0]     * (1.14.2.2)  [rel-0-4-0]

   [HEAD]                  [rel-0-4-branch]


The second file is not changed at all between the version tags. Nevertheless, all tags are available even though now they are on the same revision 1.2.


     *     (1.2) [rel-0-3-8] [rel-0-4-pre1] [rel-0-5-base]
     |           [rel-0-4-pre2] [rel-0-4-0] [rel-0-5-0]
     |\__________________________
     |                           \
     |                            |

   [HEAD]                   [rel-0-4-branch]