diff --git a/mps/procedure/index.rst b/mps/procedure/index.rst new file mode 100644 index 00000000000..62983d8c312 --- /dev/null +++ b/mps/procedure/index.rst @@ -0,0 +1,96 @@ +Memory Pool System Product Procedures +===================================== +:author: Richard Brooksby +:organization: Ravenbrook Limited +:date: 2002-06-18 +:revision: $Id$ +:confidentiality: public +:copyright: See `C. Copyright and License`_ + + +1. Introduction +--------------- + +This document lists the procedures which are applied to the product +sources of the Memory Pool System project. (Compare with the `procedures +which govern the *project* `__.) + +This document will be updated as new procedures are created. + +The readership of this document is anyone developing or extending the +product sources. + +This document is not confidential. + + +2. Procedures +------------- + +================== ================================================== +`version-create`_ Create a new MPS version branch. +`release-build`_ Build product releases from the sources. +================== ================================================== + +.. _version-create: version-create +.. _release-build: release-build + + +A. References +------------- + + +B. Document History +------------------- + +========== ======= ================================================== +2002-06-18 RB_ Created based on P4DTI document. +2005-09-30 RHSK_ Added version-create and release-configura. +2008-01-07 RHSK_ Added release-experimental. +2012-09-05 RB_ Removed release-experimental, no longer needed to work with Configura. +2012-09-13 RB_ Removed release-configura, now maintained on a custom mainline. +========== ======= ================================================== + +.. _RB: mailto:rb@ravenbrook.com +.. _RHSK: mailto:rhsk@ravenbrook.com + + +C. Copyright and License +------------------------ + +This document is copyright © 2002-2012 `Ravenbrook +Limited `__. All rights reserved. This is an +open source license. Contact Ravenbrook for commercial licensing +options. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +#. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. +#. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. +#. Redistributions in any form must be accompanied by information on how + to obtain complete source code for the this software and any + accompanying software that uses this software. The source code must + either be included in the distribution or be available for no more + than the cost of distribution plus a nominal fee, and must be freely + redistributable under reasonable conditions. For an executable file, + complete source code means the source code for all modules it + contains. It does not include source code for modules or files that + typically accompany the major components of the operating system on + which the executable file runs. + +**This software is provided by the copyright holders and contributors +"as is" and any express or implied warranties, including, but not +limited to, the implied warranties of merchantability, fitness for a +particular purpose, or non-infringement, are disclaimed. In no event +shall the copyright holders and contributors be liable for any direct, +indirect, incidental, special, exemplary, or consequential damages +(including, but not limited to, procurement of substitute goods or +services; loss of use, data, or profits; or business interruption) +however caused and on any theory of liability, whether in contract, +strict liability, or tort (including negligence or otherwise) arising in +any way out of the use of this software, even if advised of the +possibility of such damage.** diff --git a/mps/procedure/release-build.rst b/mps/procedure/release-build.rst new file mode 100644 index 00000000000..1ae33bbd116 --- /dev/null +++ b/mps/procedure/release-build.rst @@ -0,0 +1,269 @@ +Memory Pool System Release Build Procedure +========================================== +:author: Richard Brooksby +:organization: Ravenbrook Limited +:date: 2002-06-17 +:revision: $Id$ +:confidentiality: public +:copyright: See `C. Copyright and License`_ + + +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. Procedure +------------ + + +2.1. Setting up for release +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Choose a *RELEASE* name of the form *VERSION.N* (for example, 0.3.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=VERSION + RELEASE=$VERSION.N + +#. Ensure that the HTML version of the manual is up to date on the + version branch:: + + pushd version/$VERSION/manual + make checkin + popd + + If this fails with the error + ``make: sphinx-build: No such file or directory`` then you need to + install the Sphinx documentation system [Sphinx]_. + + On Mac OS X with MacPorts you can install it like this:: + + sudo port install py27-sphinx + sudo port select --set sphinx py27-sphinx + +#. Ensure that ``version/$VERSION/readme.txt`` contains an up-to-date + description of the release you intend to build and the correct + release name. + +#. In ``version/$VERSION/code/version.c``, set ``MPS_RELEASE`` to the + correct value (see the rules in the comments), and check strings that + contain copyright dates, etc. + +#. In ``configure.ac`` edit the second argument of ``AC_INIT`` to be + "``release $RELEASE``\ ", then open ``configure`` for edit and run + ``autoreconf -vif`` to bring the configure script up to date. + +#. Submit ``readme.txt``, ``version.c``, ``configure.ac``, and other + changed files to Perforce before you continue. + +#. Determine the *CHANGELEVEL* at which you’re going to make the + release. This will usually be the latest submitted changelevel on the + version branch; to get it, use ``p4 changes`` with a max of 1 (one):: + + CHANGELEVEL=$(p4 changes -m 1 version/$VERSION/... | cut -d' ' -f2) + + +2.2. Pre-release testing +~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Sync the version sources to precisely the *CHANGELEVEL* you + determined in step 2.1.1, with no extraneous files, by using the + following procedure:: + + # (you may wish to check for opened files first) + p4 revert version/$VERSION/... + rm -rf version/$VERSION + p4 sync -f version/$VERSION/...@$CHANGELEVEL + + Note: ``revert`` and ``sync -f`` are required, otherwise p4-opened or + forced-writeable files may remain or be omitted; see [RHSK_2008-10-16]_. + +#. Run the test suite:: + + (cd version/$VERSION && ./configure && make test) + + Check that the test suite passes. + + +2.3. MPS Kit Tarball and Zip file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + If you are creating a custom variant then vary the release name + according to the variant, e.g. ``mps-cet-1.110.0.zip`` + +On a Unix box: + +#. Create a Perforce client workspace that maps: + + - ``version/VERSION/...`` to ``mps-kit-RELEASE/...`` + - ``release/RELEASE/...`` to ``release/RELEASE/...`` + +#. Ensure the Perforce client workspace is set for Unix (LF) line + endings. + +#. Sync the version sources to *CHANGELEVEL* by repeating the procedure + from step 2.2.1:: + + rm -rf mps-kit-RELEASE + p4 sync -f @CHANGELEVEL + +#. Create a tarball containing the MPS sources, and open it for add:: + + mkdir -p release/RELEASE + tar czf release/RELEASE/mps-kit-RELEASE.tar.gz mps-kit-RELEASE + p4 add release/RELEASE/mps-kit-RELEASE.tar.gz + +#. Ensure the Perforce client workspace is set for Windows (CRLF) line + endings. + +#. Sync the version sources again as in step (2) above. + +#. Create a zip file containing the MPS sources, and open it for add:: + + mkdir -p release/RELEASE + zip -r release/RELEASE/mps-kit-RELEASE.zip mps-cet-kit-RELEASE + p4 add release/RELEASE/mps-kit-RELEASE.zip + +#. Revert any changes to your Perforce client line endings. (You + probably want them set to local.) + +#. Submit the release files to Perforce with the comment "MPS: adding + the MPS Kit tarball and zip file for release RELEASE." + + +2.4. Registering the release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Edit the index of releases (``release/index.html``) and add the + release to the table, in a manner consistent with previous releases. + +#. 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. + +#. Submit these changes with the comment “MPS: registered release + *RELEASE*.” + +#. Edit the main MPS Project index page (``index.html``), to refer to + the new release: + + - update links to “the latest release” or “download” (important); + - consider updating the “project status” section. + +#. Visit the `project + updater `__, + select “mps” from the dropdown, and hit “Find releases”. + +#. Inform the project manager and staff by e-mail to + mps-staff@ravenbrook.com. Consider announcing the new release by + e-mail to mps-discussion@ravenbrook.com. + + +A. References +------------- + +.. [RHSK_2008-10-16] "revert ; rm ; sync -f"; Richard Kistruck; + Ravenbrook Limited; 2008-10-16; + http://info.ravenbrook.com/mail/2008/10/16/13-08-20/0.txt + +.. [Sphinx] "Sphinx: Python document generator"; http://sphinx-doc.org/ + + +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 (§2.2). + +- 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. + +.. _RB: mailto:rb@ravenbrook.com +.. _NB: mailto:nb@ravenbrook.com +.. _RHSK: mailto:rhsk@ravenbrook.com +.. _GDR: mailto:gdr@ravenbrook.com + + +C. Copyright and License +------------------------ + +This document is copyright © 2002–2013 `Ravenbrook +Limited `__. All rights reserved. This is an +open source license. Contact Ravenbrook for commercial licensing +options. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +#. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. +#. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. +#. Redistributions in any form must be accompanied by information on how + to obtain complete source code for the this software and any + accompanying software that uses this software. The source code must + either be included in the distribution or be available for no more + than the cost of distribution plus a nominal fee, and must be freely + redistributable under reasonable conditions. For an executable file, + complete source code means the source code for all modules it + contains. It does not include source code for modules or files that + typically accompany the major components of the operating system on + which the executable file runs. + +**This software is provided by the copyright holders and contributors +“as is” and any express or implied warranties, including, but not +limited to, the implied warranties of merchantability, fitness for a +particular purpose, or non-infringement, are disclaimed. In no event +shall the copyright holders and contributors be liable for any direct, +indirect, incidental, special, exemplary, or consequential damages +(including, but not limited to, procurement of substitute goods or +services; loss of use, data, or profits; or business interruption) +however caused and on any theory of liability, whether in contract, +strict liability, or tort (including negligence or otherwise) arising in +any way out of the use of this software, even if advised of the +possibility of such damage.** diff --git a/mps/procedure/version-create.rst b/mps/procedure/version-create.rst new file mode 100644 index 00000000000..fd77eff2f7d --- /dev/null +++ b/mps/procedure/version-create.rst @@ -0,0 +1,180 @@ +Memory Pool System Version Create Procedure +=========================================== +:author: Richard Kistruck +:organization: Ravenbrook Limited +:date: 2008-10-29 +:confidentiality: public +:copyright: See `C. Copyright and License`_ +:readership: MPS developers + + +1. Introduction +--------------- + +This document tells you how to create a new version from the master +sources. (For example, if the last version of the MPS is 1.105, with +releases 1.105.0 and 1.105.1, this document tells you how to abandon the +1.105 lineage and take a new clone from the master sources to create +version 1.106). + +Background: refer to PQTCM ("Product Quality Through Change Management", +`http://www.ravenbrook.com/doc/1999/05/20/pqtcm/ `__) +for background, terminology, rationale, and usage guidance. This tells +you what "a version" actually is. + + +2. Preamble +----------- + +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 PQTCM when +deciding. (Summary: am I changing the specification?). + +What is a version? +~~~~~~~~~~~~~~~~~~ + +A version is a 'clone' of all the master source files, that then has its +own evolution. A Version has these parts: + +- Perforce branch, defining the mapping used to integrate from master + to version. By convention, the name of the branch is + "mps/version/A.BBB": note that we make the branch name exactly match + the pathname of that version's sub-tree. For example:: + + $ p4 branch -o mps/version/1.105 + ... + //info.ravenbrook.com/project/mps/master/... //info.ravenbrook.com/project/mps/version/1.105/... + ... + +- Cloned (integrated) and submitted files, in the "version/A.BBB/..." + sub-tree. Usually this is a clone of the entire "master" subtree and + all its files. These were created in a single change with "p4 + integrate -b ". This initial integrate is what populates + the version branch with files; before that it was empty. For each of + these files, Perforce reports the first action as "branch". Some + files may then be further modified. + +- Origin: The point in time that the initial integrate was performed, + expressed as its changelevel minus one, defines the "Origin" of the + version. The Origin is the last change on the master sources that + also made it into the version sources by virtue of the initial + integrate command. + +- Entry in the table at + `http://info.ravenbrook.com/project/mps/version/ `__. + +3. Procedure: How to make a new version +--------------------------------------- + +0. Some files contain an MPS version-name. What version-name do the +*master* copies of these files contain? It depends. Some contain the +pseudo-version-name "master": you will leave these files unchanged on +master, and only update them on the version branch (see step 6 below). +Others, even in master, refer to the expected next version-name: you +should update these files before making the branch. Make these files +contain the expected new version-name, and/or information pertinent to +the new version: + +- ``master/readme.txt`` +- ``master/code/version.c`` +- ``master/code/w3build.bat`` + +(check the "Setup" section of procedure/release-build for the full list +of these files) Submit these files before you continue. + +1. Make the branch: p4 branch mps/version/A.BBB Description: Branching +master sources for version A.BBB. Always the whole of master:: + + //info.ravenbrook.com/project/mps/master/... //info.ravenbrook.com/project/mps/version/A.BBB/... + +2. Make sure you have no unsubmitted files, and then:: + + p4 integrate -b mps/version/A.BBB + +3. ``p4 submit`` + +4. Determine the Origin of the new version: do p4 changes -m 5 on the + master, and note the latest change that was in before the integrate. + + .. Note: it's better to do it this way -- do the integrate from the + *implicit* tip of the master, and then check back to see what + happened -- because it's hard to get wrong. Also, then the + integrate has the changelevel origin+1. Clashes with master + submits could theoretically occur, and could be avoided by + determining the origin first and specifying it to the initial + integrate, but in practice this never happens. + +5. Update the table at . + +6. Edit Master->Version in documents that erroneously say "Master". + Always edit version/A.BBB/index.html, e.g. (case-sensitive):: + + "of the Master version" -> "of Version A.BBB" + "Master" -> "Version A.BBB" + + Less importantly, edit various other files. See change 30260. + +7. Do an empty-integrate of this change back on to the masters, so P4 + thinks it's done and doesn't keep suggesting it:: + + p4 integrate -r -b mps/version/A.BBB Version> + p4 resolve -ay Version> + + +A. References +------------- + + +B. Document History +------------------- + +- 2005-10-03 RHSK Created. +- 2006-12-27 RHSK Step 0: edit some files on master before making version branch +- 2007-07-05 RHSK Releasename now also in w3build.bat. Make sure all submitted before integ. +- 2008-10-29 RHSK Convert from text to html. +- 2010-11-06 RHSK Correctly format example of p4 branch -o mps/version/1.105 + + +C. Copyright and License +------------------------ + +This document is copyright © 2002, 2005-2008, 2010 `Ravenbrook +Limited `__. All rights reserved. This is an +open source license. Contact Ravenbrook for commercial licensing +options. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +#. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. +#. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. +#. Redistributions in any form must be accompanied by information on how + to obtain complete source code for the this software and any + accompanying software that uses this software. The source code must + either be included in the distribution or be available for no more + than the cost of distribution plus a nominal fee, and must be freely + redistributable under reasonable conditions. For an executable file, + complete source code means the source code for all modules it + contains. It does not include source code for modules or files that + typically accompany the major components of the operating system on + which the executable file runs. + +**This software is provided by the copyright holders and contributors +"as is" and any express or implied warranties, including, but not +limited to, the implied warranties of merchantability, fitness for a +particular purpose, or non-infringement, are disclaimed. In no event +shall the copyright holders and contributors be liable for any direct, +indirect, incidental, special, exemplary, or consequential damages +(including, but not limited to, procurement of substitute goods or +services; loss of use, data, or profits; or business interruption) +however caused and on any theory of liability, whether in contract, +strict liability, or tort (including negligence or otherwise) arising in +any way out of the use of this software, even if advised of the +possibility of such damage.**