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?).
+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?).
-A version is a 'clone' of all the master source files, that then has its own evolution. A Version has these parts:
+A version is a ‘clone’ of all the master source files, that then has its own evolution. A version has these parts:
+ +A version name, consisting of a major version number A and a minor version number BBB.
- $ p4 branch -o mps/version/1.105 - ... - //info.ravenbrook.com/project/mps/master/... //info.ravenbrook.com/project/mps/version/1.105/... - ... +A Perforce branch specification that defines the mapping used between the master sources and the sources on the version branch. 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 +Branch: mps/version/1.105 + +Description: + Branching master sources for version 1.105. + +View: + //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 by running p4 integrate -b mps/version/A.BBB. 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. This 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 //info.ravenbrook.com/project/mps/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/...
Consider each deprecated feature (by grepping the manual sources for deprecated:: sections) and decide whether it needs to be removed from the version you are about to make (and all subsequent versions). Remove features from the master sources before making the version branch.
-2. Make sure you have no unsubmitted files, and then:
-+
p4 integrate -b mps/version/A.BBB
Choose the version number for the new version. Typically this has the same major version number as the previous version, and the next minor version number. Thus 1.104 is followed by 1.105. [TODO: when does the major version number change?]
-3. p4 submit
Make sure you have the new version branch mapped to your client workspace: run p4 client and check that there is a mapping for //info.ravenbrook.com/project/mps/version/A.BBB/....
-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. -
+In the master sources, edit code/version.c and change MPS_RELEASE to refer to the version you are about to create (using .0 for the release), and update MPSCopyrightNotice to include the current year. Submit this file to Perforce. [Note that MPS_RELEASE in this file is used to populate the release number for the Sphinx documentation: see manual/source/conf.py.]
-[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. RHSK] -
+Determine the origin of the branch: run p4 changes -m 1 //info.ravenbrook.com/project/mps/master/... and note the output changelevel (this is called ORIGIN in the examples below).
-5. Update the table at <http://info.ravenbrook.com/project/mps/version/>. -
+Make the branch: p4 branch mps/version/A.BBB and edit the branch specification to read as follows:
-6. Edit Master->Version in documents that erroneously say "Master". +
Branch: mps/version/A.BBB + +Description: + Branching master sources for version A.BBB. + +View: + //info.ravenbrook.com/project/mps/master/... //info.ravenbrook.com/project/mps/version/A.BBB/... +
Make sure you have no unsubmitted files, and then run p4 integrate -b mps/version/A.BBB //info.ravenbrook.com/project/mps/master/...@ORIGIN and then p4 submit.
Update the table at http://info.ravenbrook.com/project/mps/version/.
+Edit Master->Version in documents that erroneously say "Master". Always edit version/A.BBB/index.html, eg. (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 +
+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 <Files Edited Master->Version> p4 resolve -ay <Files Edited Master->Version> -