Memory Pool System Release Build Procedure

author Richard Brooksby
confidentiality public
date 2002-06-17
organization Ravenbrook Limited
revision //info.ravenbrook.com/project/mps/master/procedure/release-build.rst#29

1. Introduction

This is the procedure for building a generic release of the Memory Pool System (an “MPS Kit”) from the version sources.

The intended readership of this document is Ravenbrook development staff. (If you are a user of the MPS, and want to build object code from an MPS Kit, please see the readme.txt file in the kit.)

This document is not confidential.

All relative paths are relative to //info.ravenbrook.com/project/mps/.

2. Prerequisites

  1. Make sure you have a version branch from which to make the release. If not, follow the version creation procedure first.
  2. Make sure that you can authenticate to Git Fusion, and that you have rights to push to the mps repository on GitHub. If not, follow the Git Fusion procedures first.

3. Setting up for release

  1. Choose a RELEASE name of the form VERSION.N (for example, 1.111.0), where VERSION is the number of the version you’re releasing, and N is the first unused release number (starting at zero). Look in the index of releases (release/index.html) for existing release numbers for your version.

    VERSION=A.BBB
RELEASE=$VERSION.N

  2. Check that the macro MPS_RELEASE in code/version.c has the correct value.

  3. Check that readme.txt contains an up-to-date description of the release you intend to build. For example, is the list of supported platforms still correct?

  4. Check that manual/source/release.rst contains a section with an up-to-date description of significant user-visible changes since the previous release.

  5. Determine the CHANGELEVEL at which you’re going to make the release. This will usually be the latest submitted changelevel on the branch from which you are making the release; to get it, use p4 changes -m 1:

    CHANGELEVEL=$(p4 changes -m 1 ... | cut -d' ' -f2)

4. Pre-release testing

  1. Sync the version sources to precisely the CHANGELEVEL you determined above, with no extraneous files, by using the following procedure:

    p4 opened version/$VERSION/...

    This should output "version/$VERSION/... - file(s) not opened on this client." But if there are opened files, then:

    p4 revert version/$VERSION/...

    Next:

    p4 update version/$VERSION/...@$CHANGELEVEL
p4 status version/$VERSION/...

    This should output "version/$VERSION/... - no file(s) to reconcile." But if there are discrepancies, then:

    rm -rf version/$VERSION
p4 sync -f version/$VERSION/...@$CHANGELEVEL

    See [RHSK_2008-10-16].

  2. Run the test suite:

    (cd version/$VERSION && ./configure && make test)

    Check that the test suite passes.

  3. Repeat for all supported platforms. On Windows the sequence of commands to run the test suite are:

    cd version\$VERSION\code
nmake /f w3i6mv.nmk clean testci
nmake /f ananmv.nmk clean testansi
nmake /f ananmv.nmk CFLAGS="-DCONFIG_POLL_NONE" clean testpollnone
cd ../test
perl test/qa runset testsets/{coolonly,argerr,conerr,passing}

  4. Check that there are no performance regressions by comparing the benchmarks (djbench and gcbench) for the last release and this one.

5. Making the release (automated procedure)

Run the script tool/release, passing the options:

  • -P mps — project name
  • -b BRANCH — branch to make the release from: for example version/1.113
  • -C CHANGELEVEL — changelevel at which to make the release
  • -d "DESCRIPTION" — description of the release
  • -y — yes, really make the release

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

tool/release -b version/$VERSION -d "Improved interface to generation chains." -y

6. Making the release (manual procedure)

Note

If you are creating a customer-specific variant then vary the release name according to the variant, for example, mps-cet-1.110.0.zip

On a Unix (including macOS) machine:

  1. Create a fresh Perforce client workspace:

    CLIENT=mps-release-$RELEASE
p4 client -i <<END
Client: $CLIENT
Root: /tmp/$CLIENT
Description: Temporary client for making MPS Kit release $RELEASE
LineEnd: local
View:
        //info.ravenbrook.com/project/mps/version/$VERSION/... //$CLIENT/mps-kit-$RELEASE/...
        //info.ravenbrook.com/project/mps/release/$RELEASE/... //$CLIENT/release/$RELEASE/...
END

  2. Sync this client to CHANGELEVEL:

    p4 -c $CLIENT sync -f @$CHANGELEVEL

  3. Create a tarball containing the MPS sources, and open it for add:

    pushd /tmp/$CLIENT
mkdir -p release/$RELEASE
tar czf release/$RELEASE/mps-kit-$RELEASE.tar.gz mps-kit-$RELEASE
popd
p4 -c $CLIENT add /tmp/$CLIENT/release/$RELEASE/mps-kit-$RELEASE.tar.gz

  4. Switch the Perforce client workspace to Windows (CRLF) line endings:

    p4 -c $CLIENT client -o | sed "s/^LineEnd:.local/LineEnd: win/" | p4 client -i

  5. Sync the version sources again:

    rm -rf /tmp/$CLIENT/version/$VERSION
p4 -c $CLIENT sync -f @$CHANGELEVEL

  6. Create a zip file containing the MPS sources, and open it for add:

    pushd /tmp/$CLIENT
mkdir -p release/$RELEASE
zip -r release/$RELEASE/mps-kit-$RELEASE.zip mps-kit-$RELEASE
popd
p4 -c $CLIENT add /tmp/$CLIENT/release/$RELEASE/mps-kit-$RELEASE.zip

  7. Submit the release files to Perforce:

    p4 -c $CLIENT submit -d "MPS: adding the MPS Kit tarball and zip file for release $RELEASE."

  8. Delete the temporary Perforce client:

    p4 -c $CLIENT client -d $CLIENT
rm -rf /tmp/$CLIENT

  9. Edit the index of releases (release/index.html) and add the release to the table, in a manner consistent with previous releases.

  10. Edit the index of versions (version/index.html) and add the release to the list of releases for VERSION, in a manner consistent with previous releases.

  11. Edit the main MPS Project index page (index.rst), updating the "Download the latest release" link.

  12. Submit these changes to Perforce:

    p4 submit -d "MPS: registered release $RELEASE."

7. Registering the release

  1. Visit the project updater, select “mps” from the dropdown, and hit “Find releases”.

  2. Make a git tag for the release:

    git clone ssh://git@perforce.ravenbrook.com:1622/mps-public
cd mps-public
git checkout -b version/$VERSION origin/version/$VERSION
git tag -a release-$RELEASE -F - <<END
Memory Pool System Kit release $RELEASE.
See <https://www.ravenbrook.com/project/mps/release/>.
END
git push --tags git@github.com:Ravenbrook/mps.git

  3. Go to the list of releases on Github and select "Draft a new release". Select the tag you just pushed, and set the title and description to match the other releases.

  4. Inform the project manager and staff by e-mail to mps-staff@ravenbrook.com.

  5. Announce the new release by e-mail to mps-discussion@ravenbrook.com. Include a summary of the release notes.

A. References

[RHSK_2008-10-16]Richard Kistruck; "revert ; rm ; sync -f"; Ravenbrook Limited; 2008-10-16; <https://info.ravenbrook.com/mail/2008/10/16/13-08-20/0.txt>.

B. Document History

2002-06-17 RB Created based on P4DTI procedure.
2002-06-19 NB Fixed up based on experience of release 1.100.0.
2004-03-03 RB Fixed the way we determine the release changelevel to avoid possible pending changelists.
2005-10-06 RHSK Clarify this procedure is for general MPS Kit releases; correct cp -r to -R. Add: check version.c.
2006-01-19 RHSK Correct readership statement, and direct MPS users to the mps-kit readme.
2006-02-16 RHSK Use Info-ZIP (free) for Windows archives, not WinZip.
2007-07-05 RHSK Releasename now also in w3build.bat.
2008-01-07 RHSK Release changelevel was in issue.cgi, now in data.py.
2010-10-06 GDR Use the project updater to register new releases.
2012-09-13 RB Don’t copy the readme.txt to the release directory, since it no longer has that dual role; make the ZIP file on a Unix box with the zip utility, since compatibility has improved.
2013-03-08 GDR Add testing step.
2012-09-24 RB Make sure ZIP files contain files with Windows line endings. Use a fresh Perforce client to avoid any possibility of a clash with working files. Different archive name for custom variants.
2013-03-20 GDR Ensure that manual HTML is up to date before making a release.
2014-01-13 GDR Make procedure less error-prone by giving exact sequence of commands (where possible) based on experience of release 1.112.0.
2016-01-28 RB Git repository renamed from mps-temporary to mps.
2018-07-30 GDR Git Fusion moved to perforce.ravenbrook.com.
2020-07-28 PNJ Updated licence text.