Chapter 17. Commit Policy
Prev | Part IV. Lire Developers' Conventions | Next

## Chapter 17. Commit Policy

Make sure your changes run on your own platform before committing. Try not to break things for other platforms though. Currently, Lire supported platforms are GNU/Linux (Debian GNU/Linux™, Red Hat Linux™, Mandrake Linux™), FreeBSD™, OpenBSD™ and Solaris™.

Documentation should be updated ASAP, in case it's obsolete or incomplete by new commits.

## CVS Branches

When doing major architectural changes to Lire, branches in CVS are created to make it possible to continue to fix bugs and to add small enhancements to the stable version while development continues on the unstable version. This applies mainly to the service repository. The doc and package repositories generally don't need branching.

BTW: A nice CVS tutorial is available in the Debian cvsbook package.

### Hands-on example

A branching gets announced. Be sure to have all your pending changes commited before the branching occurs. After a branch has been made, one can do this:

    $ cd ~/cvs-sourceforge/logreport
    $ mv service service-HEAD
    $ cvs co -r lire-20010924 service
    $ mv service service-lire-20010924

or (with the same result)

    $ mv service service-HEAD
    $ cvs co -r lire-20010924 -d service-lire-20010924 service

Now, when working on stuff which should be shipped in the coming release, one should work in service-lire-20010924. When working on stuff which is rather fancy and experimental, and which needs a lot of work to get stabilized, one should work in service-HEAD.

### Naming, what it looks like

Here is what branches schematically look like:

          release-20010629_1 ---> lire-unstable-20010703 ---> HEAD
                \
                 \
             lire-20010630 ---> lire-stable-20010701

In this diagram a branch named `lire-20010630` was created from the `release-20010629_1` tag. `lire-unstable-20010703` is another tag on the trunk (the trunk is the main branch). `HEAD` isn't a real tag, it always points to latest version on the trunk.

### Creating a Branch

To create a branch, one runs the command `cvs rtag -b -r `release-tag` `branch-name` `module``. Note that this command doesn't need a checkout version of the repository. For example, to create the `release-20010629_1-bugfixes` branch in the service repository, e.g. to backport bugfixes to version 20010629_1, one would use `cvs rtag -b -r release-20010629_1 release-20010629_1-bugfixes service`. When ready for release, this could get tagged as `release-20010629_2`.

The `release-tag` should exist before creating the branch. In case you want to branch from HEAD, use `-r HEAD`. E.g. `cvs rtag -b -r HEAD release_1_1-branch service`. Once Lire 1.1 gets released, tag it as `release_1_1`.

### Accessing a Branch

To start working on a particular branch, you do `cvs update -r `branch-name``. For example, to work on the `release_1_1-branch` branch, you do in your checked out version, `cvs update -r release_1_1-branch`. This will update your copy to the version `release_1_1-branch` and will commit all future changes on that branch.

Alternatively, you can also specify a branch when checking out a module using `cvs co -r `branch-name` `module``. For example, you could checkout the stable version of Lire by using `cvs co -r release_1_1-branch service`.

To see if you are working on a particular branch, you can use the `cvs status `file`` command. For example, running `cvs status NEWS` could show:

    ===================================================================
    File: NEWS             	Status: Up-to-date

       Working revision:	1.74
       Repository revision:	1.74	/cvsroot/logreport/service/NEWS,v
       Sticky Tag:		lire-stable
       Sticky Date:		(none)
       Sticky Options:	(none)

The branch is indicated by the `Sticky Tag:` keyword. If its value is `(none)` you are working on the `HEAD` branch.

To work on the `HEAD`, you remove the sticky tag by using the command `cvs update -A`.

### Merging Branches on the Trunk

You can bring bug fixes and small enhancements that were made on a branch into the unstable version on the trunk by doing a merge. You do a merge by using the command `cvs update -j `branch-to-merge`` in your working directory of the trunk. Conflicts are resolved in the usual CVS way. For example, to merge the changes of the stable branch in the development branch, you would use `cvs update -j lire-stable`.

You should tag the branch after each successful merge so that future changes can be easily merged. For example, after merging, you do in a checked out copy of the `lire-stable` branch: `cvs tag lire-stable-merged-20010715`. In this way, one week later we can merge the week's changes of the stable branch into the unstable branch by doing `cvs update -j lire-stable-merged-20010715 -j lire-stable`.

Prev | Up | Next
Some “Best Practices” on Unit Testing | Home | Chapter 18. Testing and debugging