SCM for the tclnotmuch Project

Early Notes

• The main development path will be on mainline, not trunk.

• The initial empty checkin can not be edited, so edit it (change branch name) after the first other checkin (just one file).

• Create a new branch from the initial checkin for the TEA sample - this will be treated as a vendor branch.

• Create a new branch from the initial checkin for tclconfig - this will be treated as a vendor branch.

• Both the above branches merged into mainline before work starts. Since they are disjoint sets of files there will be no conflicts and each merge should be checked in immediately so that the starting point for changes is in the repository.

• Create a new branch from the initial checkin for notmuch's own test data - this will be treated as a vendor branch, and should be merged into mainline immediately as it is a disjoint set of files.

Release Management and Branches

Note:

This may be seen as overkill for this project, but the project is being used as a prototype SCM exercise as well.

The project uses Semantic Versioning 2.0.0 with the minor variation that a version x.y.z having a z value of zero will be referred to as x.y.

There is no point in pre-release identifiers unless someone is using the version concerned, and build metadata, if needed, will be the first 10 characters of the SHA1 hash of the Fossil commit.

The project is currently in proof-of-concept mode, which will be labelled version 0.1, so the internal version labelling is set to this (including the .so name).

The first actual release will happen either

• when it is ready (in which case it will be version 0.1)

or

• when someone is using the software and reports this to the project (in which case the version will be 0.1-alpha.q where q is a number to distinguish possible multiple occurrences of this event). This type of release is likely to be created retrospectively.

What to do in Fossil for a Release

• Tag the checkin corresponding to the release as release_version where version is as above.

The trunk Branch

This does not exist.

The mainline

• x.0.0 (normally referred to as x.0) is always on mainline.

• x.y.0 (normally referred to as x.y) is always on mainline.

• Normal development proceeds along mainline from the most recent release.

When to Branch

1. When the first patch to a release is required, check out the checkin tagged for the release, make changes and, on the first subsequent check in, make it a branch with the same name as the tag on the release (parent) checkin. This is a release maintenance branch and subsequent patches should be developed and released on this branch. Note that the new branch should be created even if the base release checkin has no child checkin yet.
2. The above applies to pre-releases as well as normal non-patch releases.
3. Parallel patch releases are not permitted.
4. A pending branch may be created (from any mainline starting point) if work needs to start on a release beyond the next one planned. This should be named pending_intended-release, but the "intended release" is not binding, though the branch name should not be changed.
5. An extra branch may be created for any need to separate some specific development. This branch may have any name that does not look like one of the other names above.

When to Merge

1. A release maintenance branch is expected to be merged into mainline and to be closed at the time of the next mainline release.
2. A pending branch is expected to be merged into mainline (or a release maintenance branch) and to be closed at the time of the next release on the receiving branch (which may be mainline).
3. An extra branch is expected to be merged into mainline (or a release maintenance branch) and to be closed at the time of the next release on the receiving branch (which may be mainline).
4. All three of the above may be merged a number of times and continue development after the merge (until their final merge).