The process of making a release includes testing to ensure that the project will compile and then creating a tag and branch in Subversion. Version numbers are explained as they pertain to Simple Cart. This section discusses the structure of the repository, the goals of a release and how to create the tag and branch.
From the root of the Simple Cart repository there are three principle folders, namely trunk, tags, and branches. The trunk contains the source code for the entire project, which includes web related files and configuration sources. The tags folder contains copies only, and the branches are considered active copies. By active copy it is meant that changes can be committed against the copy. Changes should never be committed against a tag, even though Subversion would permit it.
When a release is made there are two copies of the trunk made. One is a copy into the tags folder and represents a snapshot of exactly what the project looked like at the time of release. This copy is never modified. The next copy is into the branches folder. This copy into the branches folder is modified (committed against) only when bugs are found in the release. When the bug(s) have been fixed and tested another tag is made with a Release number incremented (version numbers are explained below).
Simple Cart follows a standard convention regarding its version number. Each version number has three (3) parts in the form x.y.z. The following table explains:
Table 2.1. Version Number Definition
| Version Number Position | Position Definition |
|---|---|
| x | This is a Major Version Number. It is expected that every release for this major version number will be backward compatible with every previous release under the same major version number. |
| y | This is the Minor Version Number. When this number is odd it indicates a development release and should probably not be used in a production environment. Even numbers represent stable releases and can be trusted for use in production. |
| z | This is a Release Version Number. Every time a formal release takes place, either in development or on a stable branch, this number is incremented. This number alone tells nothing about whether this release is table or not. |
A release should be triggered by a milestone. Milestones may relate to new features that have been requested, or they may be in response to a bug. In either case the use of issue tracking software will aid in determining what milestones are of importance, and when those milestones are released.
All Automated tests should be run successfully before preparing a release. If in the process of making a release it is found that a test fails, the process should be stopped and the problem addressed. Once all tests are running successfully the release can be made.
Every branch and tag name should not the version number. The format for the name is as follows: BRANCH_X_Y_Z_YYYY_MM_DD. In this format the X, Y and Z correspond to the x, y and z in the version number respectively, as explained in the previous section. The underscores are literal. YYYY indicates a four number year (e.g. 2005), with MM and DD indicating the two digit month and day respectively.
![[Note]](images/note.png) | Note |
|---|---|
| Branches should only ever have a value of zero for Z in the above format. This is a consequence that a branch is only made for stable (even minor number) release. Tags may, however, have a non zero value for Z. |
A tag name is derived in the same manner except that the literal occurrence of BRANCH is replaced with TAG as in the following example: TAG_X_Y_Z_YYYY_MM_DD.
Every Even numbered minor release (this corresponds to the y in x.y.z) requires a branch. The purpose of a branch is to move work and commits away from the main development trunk. This is important for two reasons. First, this ensures that no new development will affect the released branch, thus introducing new bugs in an official release. Second it facilitates the process of applying fixes to software that may be in production use, so that only the affected code will be updated with the fix.
Branches are not required for releases with a minor odd numbered. This is due to the fact that no one should be using the release in production and so all changes and bug fixes should be included in the trunk.
To create a branch do the following:
Checkout a clean copy of the source code and run all tests. No commits against the trunk should be permitted during the process of making a branch.
From within the checked out code use the copy command as follows:
svn copy trunk branches/new-branch-name.The copy must now be committed as follows:
svn commit -m "Notes about new branch"
The same copy can be accomplished with a single command as below:
svn copy https://svn.sourceforge.net/svnroot/simplecart/trunk \
https://svn.sourceforge.net/svnroot/simplecart/branches/new-branch-name \
-m "Notes about new branch"
Which method you choose is a matter of preference.
| Note |
|---|---|
| The second method requires no commit and is final once it is issued. If you plan to review the copy before committing use the first method instead. |
Every release, both for Major and Minor versions, both Odd and Even, should be tagged. Since a tag is never changed these become very useful snapshots of the state of code at a particular point in time and help in debugging. The process for creating a tag is the same as creating a branch.
To create a tag do the following:
Checkout a clean copy of the source code and run all tests. No commits against the trunk should be permitted during the process of making a tag.
From within the checked out code use the copy command as follows:
svn copy trunk branches/new-tag-name.The copy must now be committed as follows:
svn commit -m "Notes about new tag"
The same copy can be accomplished with a single command as below:
svn copy https://svn.sourceforge.net/svnroot/simplecart/trunk \
https://svn.sourceforge.net/svnroot/simplecart/branches/new-tag-name \
-m "Notes about new tag"
Which method you choose is a matter of preference.
| Note |
|---|---|
| The second method requires no commit and is final once it is issued. If you plan to review the copy before committing use the first method instead. |
Tags are intended to be a snapshot of exactly what the code looked like a a given point in time. A tag cannot accept commits (or at least it should not), while a branch can. For this reason, each release with an even minor number which is intended for production use should be placed in a branch that can accept bug fix commits. This will ensure that no new changes creep in from new development.