# Management of the Acedb releases

Ensure these three environmental variables are set correctly.

    CVSROOT /nfs/disk100/acedb/CVS_ACEDB
    CVSEDITOR emacs
    CVSREAD

## Make a release from the main branch

The current development is happening in acedb version "4.8". The number 4 is the version number, and '8' is the release number. We use even release numbers for the inhouse development, and odd release numbers for the public releases. (e.g. 4.5 or 4.7)

The next public release will carry the acedb-version stamp "4.9", which will be a stable and tested version of our 4.8 development tree. These instructions are for the case that we will officially release that version 4.9 into the public domain.

Note, that the words check in and check out are used in the way RCS used to deal with those actions, under CVS they have slightly different meanings and the names of CVS commands don't match the original meaning from RCS.

Check the file wnq/aceversion.c and make sure it shows the version number that your release is about to carry. If not, edit the file and check it back in.

Make sure all collaborators have checked in and tested their last set of changes that are to be present in the release. Ask all of them to stop checking in changes for the day the release is being made.

Note that they can start checking out files and continue to work on new things for the next release straight away, just keep everybody from checking files back in for a half a day or so.

All of the following instructions should be carried out on a disk with quite a bit of disk-space left.

    % mkdir acedb4_9
    % cd acedb4_9
    % cvs checkout `cat $CVSROOT/DIRECTORIES.full-release`
    % ln -s wmake/makefile .

This will give you a working copy of the up-to-date status of the repository. You are hereby duplicating your working directory in a different directory.

The advantage is that you'll only be given files that have a current entry in the repository. All those files like emacs leftovers (`#filename.c#` or `filename.c~`) are thereby excluded from that new working copy.

You are now ready to freeze the source code tree in the version that you have just retrieved :

    % cvs tag RELEASE-4_9 `cat $CVSROOT/DIRECTORIES.full-release`

The CVS manual explains this command as follows:

Use this command to assign symbolic tags to the nearest repository versions to your working sources. The tags are applied immediately to the repository ...

One use for tags is to record a snapshot of the current sources when the software freeze date of a project arrives. As bugs are fixed after the freeze, only those changed sources that are to be part of the release need to be re-tagged.

The symbolic tags are meant to permanently record which revisions of which files were used in creating a software distribution. The checkout and update commands allow you to extract an exact copy of a tagged release at any time in the future, regardless of whether files have been changed, added, or removed since the release was tagged.

This working copy you have is now exactly what the release is going to contain. Please do not run the tag command on your own everyday working copy as it may contain temporary files or your local versions may not be exactly what's represented in the repository. We have experienced problem with tagging local working copies, so please make sure you tag a working copy that you have just pulled out of the repository.

The temporary `acedb4_9/` working directory can be removed. It was only used to tag the repository more precisely. Now that the tag is in the CVS system, the files for the release can be pulled out of the repository directly based on the version tag in the CVS tree.

The repository is now in a post-release state, which increases the current minor release number by one to the next even number. The post-release state is therefor reflected by the even number, which marks the latest version of the repository as an inhouse development version.

Go to your normal working copy and ...

     update your normal working copy from the repository.
     check out wnq/aceversion.c
     edit the ACEDB_RELEASE number to be the next even number ('10' in this example)
     check the file back in

Now is a good time to ask every collaborator to update their normal working copy of the main-trunk as the tagging is complete now. They are now free to continue working on the tree, but all edits from now on won't be part of this new release.

Now tar up the directories and pre-compile the binaries as usual. I will describe a tried and tested way that works for me.

Log in as user 'acedb'. You will now have access to a set of commands in ~acedb/cvs_scripts/ . I use the script `makerelease` which will compile the specified release. Type :

    % makerelease 4_9 4_8 <username>

This command will extract the previously tagged version of the source tree (i.e. `RELEASE-4_9`) from the repository and compile a set of given programs. It uses the same script used in the overnight-build to do this. The resulting directories will be

      ~acedb/RELEASE.4_9/bin.ALPHA_4
                         bin.SOLARIS_4
                         ...
      ~acedb/RELEASE.4_9.BUILD/w1
                               w2
                               w...
    			   ...

The second argument given to `makerelease` is the version-id of the last release. This is used to create a file containing changes between the current release and the previous one.
The third argument is your username, which will be used to mail error reports to, if something goes wrong.

## Applying bugfixes to an existing release

Once a version has been frozen and released, you will probably receive bug-reports from users. Without disturbing the main development it is possible to fix those bugs in the released version and re-release a patched version.

If the bug fix is going to impact the current development code, apply and test the fix there first. You will be working in your normal working directory, which you use with the AC scripts.

Carefully choose which changes are really necessary to be included in the patch-release, simple changes that otherwise crash the program are a good candidate, but changes in the layout of buttons or new functions should wait till the next major release.

First you need to create a branch from the main trunk of the tree which is rooted at the previous release tag, in this case `RELEASE-4_9`. The commands are:

    % cd <anywhere>
    % cvs rtag -b -r RELEASE-4_9 release-4_9-patches `cat $CVSROOT/DIRECTORIES.full-release`

This is what the CVS manual has to say about the last command :

The rtag command can be used to create a branch. The rtag command is much like tag, but it does not require that you have a working copy of the module. ...

The '-b' flag makes rtag create a branch (rather than a symbolic revision name). '-r RELEASE-4_9' says that this branch should be rooted at the node (in the revision tree) that corresponds to the tag '-r RELEASE-4_9'. Note that the numeric revision number that matches '-r RELEASE-4_9' will probably be different from file to file. The name of the new branch is '-r RELEASE-4_9-patches', ...

To fix a problem with the public 4.9 release you need a working copy of the branch you've just created :

    % mkdir acedb4_9-patches
    % cd acedb4_9-patches
    % cvs checkout -r RELEASE-4_9-patches `cat $CVSROOT/DIRECTORIES.full-release`

All patch-level bugfixes happen in this working directory. The state of this branch will be frosen at regular intervals, and the different stages of the patch-branch will get the ACEDB_UPDATE letter 'a', 'b' 'c' etc.

Assume a user has reported a problem in `w4/parse.c`. You know of a quick fix, but you have more elaborate changes in mind for future releases. Apply all those elaborate changes (which may involve restructuring modules, renaming files etc.) in the main trunk of the development. This is the normal working copy of your tree normally accessed by the AC scripts.

In order to apply the quick-fix version of the fix to the patch-branch, go to the `acedb4_9-patches` working copy you've just created.

    % cd acedb4_9-patches/w4
    % cvs edit parse.c
    % emacs parse.c
    ----- apply the quick fix in the file ------
    % cvs commit parse.c

If you want to more or less duplicate a main trunk change in the patch-branch, it is helpful to use the split-screen mode of emacs, when you have a read-only main trunk version in the left screen-half, and you're editing the checked out branch copy in the right half, whilst comparing the two side-by-side.

Normal rules apply to this working directory of the patch-branch, make sure you are up-to-date with the modifications other people are making to the patch-branch. Communicate to other collaborators which fixes should be applied and when. Keep a record of your fixes for the release notes. It is important to maintain a well-kept changelog for the patch-branch, so users know if there bug has been fixed in the next patch level.

## Releasing a bug-fixed patch-version

Once you have applied all the necessary bug-fixes to patch-branch, it may be time to release a patched version, In this case RELEASE-4_9a. You need to freeze the current state of the branch and give this frozen state a letter code.

    % cd acedb4_9-patches
    % cvs edit wnq/aceversion.c
    % emacs wnq/aceversion.c
    ----- change ACEDB_UPDATE letter to 'a' ------
    % cvs commit wnq/aceversion.c
    % cvs tag RELEASE-4_9a `cat $CVSROOT/DIRECTORIES.full-release`

Now tar up the directories and pre-compile the binaries as usual, but this time based on the new RELEASE-4_9a tag.

              -------- Instructions to follow ---------

The working copy of the patch-branch should be treated in the same way as the normal working directory. That means all collaborators who have worked on patch-level bug-fixes should update their working copy of the patch-branch.

    % cd acedb4_9-patches
    % cvs update w*

You can now apply more bugfixes and free the patch-branch some other time, with a new update letter, and re-release by repeating the steps above.

NOTE : There will only ever be one patch branch per major release number, it's name will be `<public-release-tag>-patches`. The different states of this branch are tagged as update-release 'a', 'b' 'c' etc.