Release Notes

There are two places to document changes that you make to the code. One is in the cvs commit comments and the other is in the release notes. I want comments within the code to describe only current behaviour of the code, not its history; we have cvs to maintain history. The role of the release notes is:

• To give a big picture view of the intent and meaning of changes. We can use cvs diff to look at the fine details.
• Often one change touches several, or even many, files. Use the release notes to describe the big picture of the overall change and to say which files were part of that change. Normally there is no need to document details of the changes; cvs diff can look after that.

When commiting files it will sometimes be useful to refer to the release notes in the commit comments.

When you check out Offline, you will see a subdirectory named ReleaseNotes, which contains subdirectories v0 and v1; later on it will get v2, v3 and so on. You can also view the ReleaseNotes via the code browser.

The directory ReleaseNotes/v1 contains files with names like, v1_0_0.txt, v1_0_1.txt and so on. Each file holds the release notes for a tagged version of our Offline code. The file v1_0_0.txt holds the release notes for version v1_0_0 and so on.

Here is the tricky part. Once we tag the cvs HEAD with a version number, all new commits will become part of the tag with the next version number. Suppose, for example, that the last tag was v1_0_8 and that the next tag will be v1_0_9; in this example new commits should be documented in the file v1_0_9.txt

Normally it will be safe to find the file with the highest version number and to add your information to that file. On rare occasions, I have done a tag and forgotten to make the next release notes file. If you notice this, fix it yourself and then let me know. When you add information to a release notes file, use the previous entries as a model.

After you have editted the release notes, remember to commit your changes!

Security, Privacy, Legal