EPICS V4 C++ Bundle Release Checklist

V4-CPP-checklist.md

EPICS V4 C++ Bundle Release Checklist

Some of the non-git commands below are recorded for Andrew's benefit and might not work for other people.

1. Check out the bundleCPP module and configure the modules

   $ git clone --recursive --branch release/4.6.0 git@github.com:epics-base/bundleCPP.git
   $ make config EPICS_BASE=/path/to/base

   If the new release branch doesn't exist yet it will have to be created; no instructions here for that yet. The instructions below assume the working copy has that release branch checked out.

2. Edit the README.md and documentation/RELEASE_NOTES.md files, updating the bundle version number in the titles and making any other general changes necessary, e.g. to the build instructions. Commit these changes to git.

3. Starting with pvCommonCPP and working in order of the module build dependencies, go into each submodule and check out the appropriate release branch for that module. For example:

   $ cd pvCommonCPP
   $ git checkout release/4.2
   $ git pull

4. See if the module owner has already tagged the release version.

   $ git tag -l '4.2.*'

   If the expected tag already exists, any updates discovered in step 5 below would require a new version number to be used. Discuss the issue with the module owner before modifying the version number. If the change is minor and the module works OK without it these updates may be skipped.

5. Check all documents and Makefiles in the pvCommonCPP module for the module's version number and release date. This includes the top-level README.md, documentation/* and SHRLIB_VERSION in src/Makefile etc.

   $ git grep '4\.2'

   Update these files as necessary. Commit these changes to git but, don't push the commits to github yet.

   $ git gui
   $ git commit -m "Update module version and release date for V4.6.0"

   Note: The git gui interactive program makes commits easier and safer than using git commit directly. Its ability to only commit a subset of the changes that have been made to a file is especially useful at times.

6. Build the module, and if it has self-tests run them:

   $ make -sj
   $ make -s runtests

7. If a module's tag has not changed since the previous bundle release, steps 7 and 8 will not be required. Assuming the tests completed successfully in step 6 and the tag has not already been applied (step 4 above), tag the module, then push the tag with any commits to github in a single git push command:

   $ git tag -m "ANJ: Tagged for V4.6.0 release" 4.2.2
   $ git push --tags origin release/4.2

   Pushing both commits and tags in a single command triggers the cloudbees documentation job to publish the generated documentation automatically. If this doesn't work (or there were no commits to push along with the tag), the release-4.2-doc job can be triggered manually on the cloudbees website after pushing the tag to github.

8. Back in the bundleCPP module, update the module's area of documentation/RELEASE_NOTES.md with any new entries from its documentation/RELEASE_NOTES.md file. For a new release branch, remove any entries that may be present from previous releases. The module's version number in the bundle's RELEASE_NOTES.md file should match the intended tag for that module. Commit these changes and the updated pvCommonCPP submodule to the bundleCPP git repository:

   $ cd ..
   $ git add pvCommonCPP documentation/RELEASE_NOTES.md
   $ git commit -m "Updated pvCommonCPP to version 4.2.2"

   The bundle should now see the submodule status at the new tag, e.g.:

   $ cd ..
   $ git submodule status pvCommonCPP
    aa8839cf73fe4ab75086e95d2f3a9c3eebb40fc3 pvCommonCPP (4.2.2)

9. Repeat steps 3 through 7 above for the remaining V4 modules except for pvaPy, in dependency order.

10. The pvaPy module cannot be configured for building until after its dependent modules have been compiled. The simplest way to build pvaPy is from the bundleCPP directory:

    $ make pvaPy

    This runs make $EPICS_HOST_ARCH in all of the dependent submodules first to ensure they have been built, then configures and builds the pvaPy module.

Remaining steps as I think of them:

• Complete the release planning document tables

• Commit final updates to the bundle, its release notes and/or the README.md file.

• Tag bundleCPP and push the tag and commits to github.

• Generate the tarfile (git archive doesn't do submodules...), upload to SF

  $ git clone --recursive --branch 4.6.0-rc1 bundleCPP EPICS-CPP-4.6.0-rc1
  $ rm -rf EPICS-CPP-4.6.0-rc1/.git EPICS-CPP-4.6.0-rc1/*/.git
  $ tar cfz EPICS-CPP-4.6.0-rc1.tar.gz EPICS-CPP-4.6.0-rc1
  $ zip -q -r EPICS-CPP-4.6.0-rc1.zip EPICS-CPP-4.6.0-rc1

• Create and populate the docbuild/4.6.0/ tree in pvDataWWW/mainPage

• Convert RELEASE_NOTES.md files to HTML for upload to the new tree:

  tux-vm-rhel7$ markdown2 RELEASE_NOTES.md > RELEASE_NOTES_CPP.html

  The output from the markdown2 program lacks an HTML header, merge the result into the EPICS V4 standard document format (use the index.html file as a template, it has the correct relative paths in it).

• Check all module documents have been published on SF docbuild/module/version. Manually trigger document generation jobs on cloudbees for any missing.

• Run the script to generate soft-links in SF docbuild/4.6.0 area

• Send announcement to tech-talk

• Update website literature.html page

• What about the other tarfile bundle containing Base too? Use the same or a different bundle, or put all the V4 modules under src?