Superwaba CVS branching policy.

Thx to Kambiz Darabi & Joshua Patterson for their useful comments.

Why?

Branches are a feature of CVS that allows development to be partitioned so that one stream does not affect the other. Branching is used to apply bug fixes to a released version, be isolated from other developers to apply deep changes or new temporary unstable features. In order to reduce the errors in branch management the most common management tasks may be automated through perl scripts. Or by using an IDE which supports the CVS branch and merge mechanisms.

How many branches?

To work successfully with branches, we would like to adhere to these commonly admitted principles

• Minimize the number of branches active at any one time.
• Minimize the complexity - that is, the depth - of our branching scheme.
• Use consistently named tags to mark all branch and merge events.

These principles are a main requirement to minimize the source control overhead and concentrate on the most effective tasks.

Trunk

The trunk or MAIN branch (sometimes called HEAD) is the CVS default created branch. This branch is the MAIN integration branch to which other potential development branches are merged to prepare a release. Small changes, which do not involve many files and design changes can also be performed on the MAIN branch.

Release branches

Release branches are created when a Superwaba version is identified as a candidate for release and are rooted on a release tag placed on the trunk. Release branches are updated with bug fixes that are committed in these branches and may be merged if required to the unstable trunk.
Even if the branch is not created at the release time, the release tag can be used later as the anchor for the release/fix branch if required.

Other development branches

As the trunk is shared by several developers, and it should be kept in a more or less stable condition, it would be too dangerous to allow performing architectural changes which involve many files directly on the trunk. Therefore, for such development, one or more developers can decide to create a feature development branch, so the changes are isolated and do not disturb other developers. However, there are some basic rules concerning the naming conventions of tags and branches.

We decided that the simplest approach called the flying fish approach technique will fit our needs best. It involves creating a branch when there is a need for a separate thread of development, and abandoning the branch once all the changes are merged with the trunk.

Tags & Branching rules

New release

Once a new release vXYY (where X is the major release number, YY the minor number in the 00 to 99 range) is scheduled all developers are asked to merge back the changes they want to deliver from their development branches into the trunk (MAIN/integration branch). After the trunk passes the required TestSuite^?, it is tagged with a label vXYY_rc0 and released to the public for testing.

During this integration (release preparing) mode, the activity in the trunk should be limited to bug fixes and minor changes to stabilize the version to release. This process will be re-iterated to build several release candidates vXYY_rcN (where N is the iteration counter) as many times as necessary to yield a sufficiently stable version which is then tagged and released as the official vXYY release.

Bug fixing

Bugs concerning a specific release vXYY should be applied to the corresponding vXYY branch and merged to the trunk if needed. Important bug fixes may be also merged to previous release branches.

New features branch

When a developer must be isolated, a new branch is created after announcing it on the developer mailing list. We follow the guidelines of the flying fish approach strategy.

• First, the MAIN branch is tagged to identify the starting point or the anchor of the new branch. This label should be Root_feature_<name>_x where name are join capitalized words describing the feature for which the branch was created and x is the iteration number starting with 1.

• The branch is then created based on this tag and the branch name should be feature_<name>_x. For instance feature_NewListBox_1 may be the first development branch to add a new listbox widget.

• Once the branch is ready to be merged back to the parent branch, a label named Pre_merge_feature_<name>_x is placed on the parent branch before the merge.

• And finaly, a label Post_merge_feature_<name>_x is placed on the parent branch after the merge is complete.

For long term branches several iterations may be required to stay tuned and may be scheduled by the parent branch and the development branch maintainers, who have to follow the development on the MAIN branch carefully.