EPICS Base Release Procedures & Checklist

This document describes the procedures and provides a checklist of tasks that should be performed when creating production releases of EPICS Base.

The Release Process

Full Process

The version released on the Feature Freeze date is designated the first pre-release, -pre1. The first release candidate -rc1 is the first version that has undergone testing by the developers and has shown no problems that must be fixed before release. New versions should be made at about 2-weekly intervals after the -pre1 release, and designated as either pre-release or release candidate versions by the Release Manager. Release candidates are announced to the whole community via the tech-talk mailing list, pre-releases are announced to to the developers via the core-talk list. After a release candidate has been available for 2 weeks without any new problems being reported or major changes having to be committed, the final release can be made.

Short Process for Patch Releases

The Patch Release date and its scope are agreed upon a few weeks ahead of the release. If no blocking issues are raised, the release is made by the Release Manager on or as soon as possible after that date, following the steps below starting at Release Approval.

Roles

The following roles are used below:

Release Manager ()
Responsible for managing and tagging the release
Platform Developers (optional)
Responsible for individual operating system platforms
Application Developers
Responsible for support modules that depend on EPICS Base.
Website Manager (Andrew Johnson)
Responsible for the EPICS website
Check Who Description
Preparing for a release
  Release Manager Email all developers about the upcoming release and ask for a list of remaining tasks that must be finished.
  All developers Check the bug tracker for any outstanding items and handle appropriately. All bugs that have been fixed should have been marked as Fix Committed.
  Release Manager Set the Feature Freeze date, by which time all Git commits for enhancements and new functionality should have been completed. After this date, commits should only be made to fix problems that show up during testing.
  Release Manager
& all developers
Ensure that documentation will be updated before the release date:
  • Application Developers Guide
  • Release Notes
  • Known Problems
  • Other documents
  Release Manager Review and update this checklist for the upcoming release.
  Website Manager Create a release milestone on Launchpad. If a target release date is known set "Date Targeted" to the expected release date. Note that pre-release and release-candidate versions should not get Launchpad milestones, only the final release.
Creating pre-release and release-candidate versions
Release Manager Edit and commit changes to the EPICS version number file configure/CONFIG_BASE_VERSION.
Release Manager Tag the module in Git, using these tag conventions:
  • R7.0.5-pren — pre-release tag
  • R7.0.5-rcn — release candidate tag
cd base-7.0
git tag -m 'ANJ: Tagged for 7.0.5-rc1' R7.0.5-rc1
Note that submodules must not be tagged with the version used for the top-level, they each have their own separate version numbers that are only tagged at the final release.
Release Manager Export the tagged version into a tarfile. The make-tar.sh script generates a gzipped tarfile directly from the tag, excluding the files and directories that are only used for continuous integration:
cd base-7.0
./.tools/make-tar.sh R7.0.5-rc1 base-7.0.5-rc1.tar.gz base-7.0.5-rc1/
Create a GPG signature file of the tarfile as follows:
gpg --armor --sign --detach-sig base-7.0.5-rc1.tar.gz
Release Manager Test the tarfile by extracting its contents and building it on at least one supported platform.
Website Manager Copy the tarfile and its signature to the Base download area of the website and add the new files to the website Base download index page.
Website Manager Create or update a website subdirectory to hold the release documentation, and copy in selected files from the base/documentation and base/html directories of the tarfile.
Website Manager Create or modify the webpage for the new release with links to the release documents and tar file. Pre-release and release-candidate versions should use the page and URL for the final release version number.
Testing
  Platform Developers Run the built-in test programs on all available host platforms using
make -s runtests
  Platform Developers Run the CA client side regression tests on all available host platforms.
  Platform Developers Check that all makeBaseApp templates build and run properly, all xxxApp and xxxBoot types and any internal options, e.g. setting STATIC_BUILD=YES or using a different INSTALL_LOCATION in configure/CONFIG_SITE.
  Platform Developers Build the SNL Sequencer against this version of Base, and check that the makeBaseApp example builds and runs correctly with it.
  Application Developers Build external applications against this version of Base on all available platforms and test as appropriate. Application code changes may be necessary where the EPICS Base APIs have been modified.
  Release Manager Check that documentation has been updated:
Release Approval
Release Manager Obtain a positive Ok to release from all platform developers once a release candidate version has gone for 2 weeks without any major new issues being reported.
Creating the final release version
Release Manager

For each external submodule in turn (assuming it has not been tagged yet):

  1. Check that the module's Release Notes have been updated to cover all changes; add items as necessary, and set the module version number and release date if appropriate. Convert to HTML and view in a browser to check the formatting:
    cd base-7.0/modules/<module>/documentation
    pandoc -f gfm -t html -o RELEASE_NOTES.html RELEASE_NOTES.md
    Commit changes (don't push yet).
  2. Edit the module's release version file configure/CONFIG_module_VERSION and its top-level Doxyfile; set the DEVELOPMENT_FLAG value to 0 and remove -dev from the PROJECT_NUMBER string. Commit changes (don't push).
  3. Tag the module:
    git tag -m 'ANJ: Tag for EPICS 7.0.5' <module-version>
  4. Update the git submodule on the Base-7.0 branch to the newly-tagged version, but don't commit yet:
    cd base-7.0/modules
    git add <module>
    git submodule status --cached
  5. Edit the module's release version file configure/CONFIG_module_VERSION and its top-level Doxyfile; increment the MAINTENANCE_VERSION, set the DEVELOPMENT_FLAG value to 1, and update the PROJECT_NUMBER string, appending -dev to the new module version number. Commit changes.
  6. Push commits and the new tag to the submodule's GitHub repository:
    cd base-7.0/modules/<module>
    git push --follow-tags upstream master

Commit all the submodule updates to the 7.0 branch.

Release Manager Edit the main EPICS Base version file and the built-in module version files:
  • configure/CONFIG_BASE_VERSION
  • configure/CONFIG_LIBCOM_VERSION
  • configure/CONFIG_CA_VERSION
  • configure/CONFIG_DATABASE_VERSION

Version numbers should be set according to the level of changes made since the last release. Note that the MAINTENANCE_VERSION or PATCH_LEVEL value should have been incremented after the previous release tag was applied. Set all DEVELOPMENT_FLAG values to 0 and EPICS_DEV_SNAPSHOT to the empty string.

Commit these changes (don't push).

Release Manager Tag the epics-base module in Git:
cd base-7.0
git tag -m 'ANJ: Tagged for release' R7.0.5

Don't push these commits or the new tag to the Launchpad repository yet.

Release Manager Edit the main EPICS Base version file and the built-in module version files:
  • configure/CONFIG_BASE_VERSION
  • configure/CONFIG_LIBCOM_VERSION
  • configure/CONFIG_CA_VERSION
  • configure/CONFIG_DATABASE_VERSION

Version numbers should be set for the next expected patch/maintenance release by incrementing the MAINTENANCE_VERSION or PATCH_LEVEL value in each file. Set all DEVELOPMENT_FLAG values to 1 and EPICS_DEV_SNAPSHOT to "-DEV".

Commit these changes (don't push).

Release Manager Export the tagged version into a tarfile. The make-tar.sh script generates a gzipped tarfile directly from the tag, excluding the files and directories that are only used for continuous integration:
cd base-7.0
./.tools/make-tar.sh R7.0.5 ../base-7.0.5.tar.gz base-7.0.5/
Create a GPG signature file of the tarfile as follows:
cd ..
gpg --armor --sign --detach-sig base-7.0.5.tar.gz
Release Manager Test the tar file by extracting its contents and building it on at least one supported platform. When this succeeds the commits and new git tag can be pushed to the Launchpad repository:
git push --follow-tags upstream 7.0
Publish to epics.anl.gov
Release Manager Copy the tarfile and its signature to the Base download area of the website.
Website Manager Update the website subdirectory that holds the release documentation, and copy in the files from the base/documentation directory of the tarfile.
Website Manager Update the webpage for the new release with links to the release documents and tar file.
Website Manager Add the new release tar file to the website Base download index page.
Website Manager Link to the release webpage from other relevent areas of the website - update front page and sidebars.
Website Manager Add an entry to the website News page, linking to the new version webpage.
Publish to epics-controls
Website Manager Upload the tar file and its .asc signature file to the epics-controls web-server.
scp base-7.0.5.tar.gz base-7.0.5.tar.gz.asc epics-controls:download/base
Website Manager Follow instructions on Add a page for a new release to create a new release webpage (not required for a patch release, just edit the existing page). Update the TablePress "Point Releases" table and add the new download, and adjust the XYZ Html Snippet for the series download.
Publish to Launchpad
Website Manager Go to the Launchpad milestone for this release. Click the Create release button and add the release date. Put a URL for the release page in the Release notes box, and click the Create release button. Upload the tar file and its .asc signature file to the new Launchpad release page.
Release Manager Find all Launchpad bug reports with the status Fix Committed which have been fixed in this release and mark them Fix Released.
Make Announcement
Release Manager Announce the release on the tech-talk mailing list.