2.1. Do I need this procedure?

You might not need to create a new version. An alternative is to create a further "point release" on the existing version. Refer to [RB_1999-05-20] when deciding. (Summary: if changing the specification, make a new version; if improving the product against an unchanged specification, make a point release.)

2.2. What is a version?

A version is a clone of all the master sources, that has its own evolution. A version has these parts:

1. The version branch specification, which defines the mapping used to integrate from the master sources to the version sources. By convention, the name of the branch specification is mps/version/A.BBB so that it exactly matches the path name of the version's sub-tree. For example:

   $ p4 branch -o mps/version/1.105
   ...
   View:
           //info.ravenbrook.com/project/mps/master/... //info.ravenbrook.com/project/mps/version/1.105/...
   ...
   

2. The version sources, in the version/A.BBB/... sub-tree. Usually these are clones of the master sources, and were created in a single change with p4 integrate -b BRANCH. Some files may then be further modified.

3. The version origin, the last change on the master sources that made it into the version sources by virtue of the initial integrate command.

4. An entry in the table of versions.

3.1. Pre-branch checklist

1. Are you an authenticated Git Fusion user? If not, follow the follow the Git Fusion procedures first.
2. Does code/version.c in the master sources contain the correct value for the MPS_RELEASE macro? It should be the name of the first release from the version you are about to create. If it is wrong, correct and submit it.
3. Does code/version.c in the master sources have the correct copyright dates for the MPSCopyrightNotice string? It should include the current year. If it is wrong, correct and submit it.

3.2. Automated procedure

Run the script tool/branch, passing the options:

• -P mps — project name
• -p master — parent branch
• -C CHANGELEVEL — changelevel at which to make the branch
• -v — request a version branch
• -d "DESCRIPTION" — description of the branch (see below)
• -g — create a corresponding Git branch using Git Fusion

The branch description will be published in the version index and should be a short summary of the improvements detailed in the release notes.

If omitted, the project and parent branch are deduced from the current directory, and the changelevel defaults to the most recent change on the parent branch. A typical invocation looks like this:

tool/branch -v -d "Improved interface to generation chains." -g

Visually check the output of the script against 3.3. Manual procedure, and when satisfied, repeat the invocation with the -y option.

3.3. Manual procedure

1. Create the version branch specification by running:

   VERSION=A.BBB
   BRANCH=mps/version/$VERSION
   p4 branch -i <<END
   Branch: $BRANCH
   Description: Branching master sources for version $VERSION.
   View: //info.ravenbrook.com/project/mps/master/... //info.ravenbrook.com/project/$BRANCH/...
   END
   

2. Create the branch itself by running:

   p4 populate -b $BRANCH -d "Branching master sources for version $VERSION."
   

3. Determine the origin of the new version:

   p4 changes -m 5 //info.ravenbrook.com/project/mps/master/...
   

   Note the latest change that was in before the populate.

4. Update the table of versions.

5. Add the version to the “mps” and “mps-public” repos published by Git Fusion by editing //.git-fusion/repos/mps/p4gf_config and //.git-fusion/repos/mps-public/p4gf_config with entries similar to existing version branches.

3.4. Post-branch checklist

Ensure that the branch appears correctly at:

1. the internal index at https://info.ravenbrook.com/project/mps/version
2. the external index at https://www.ravenbrook.com/project/mps/version
3. the GitHub mirror at https://github.com/Ravenbrook/mps/branches