EPICS Release Procedures & Checklist

# 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

We used to have one written down here, but we weren't following it very closely so now the decision to make a new release is taken during the Core Developers bi-weekly meetings in an informal manner. The steps detailed below were written to remind Andrew (or anyone else who does the release) about everything that has to be done since it's so easy to miss steps.

### Roles

The following roles are used below:

Release Manager
  Responsible for managing and tagging the release
Core Developers
  Responsible for maintaining the EPICS software
Application Developers
  Responsible for support modules that depend on EPICS Base.
Website Editors
  Responsible for the EPICS websites

Check | Who | Description
--- | --- | ---
Preparing for a release
| Release Manager | Notify core developers about the upcoming release and ask about any remaining tasks that must be finished.
| All developers | Check the bug tracker for any outstanding items and handle appropriately.
| Release Manager | Set a Feature Freeze date, by which time all Git branches for enhancements and new functionality should have been merged. After this date, commits and merges 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: Release Notes Doxygen annotations Other documents
| Release Manager | Review and update this checklist for the upcoming release. Update the release version number in the tags and messages below.
Testing
| Platform Developers | Run the internal 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 Notes Doxygen annotations Other documents
Release Approval
| Core Developers | Reach a consensus that the software is ready to release.
Creating the final release version
| Release Manager | For each external submodule in turn (assuming it has not been tagged yet): `git grep UNRELEASED` and insert the module version to any doxygen annotations that have a `@since UNRELEASED` comment. Commit (don't push yet). 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 these changes (don't push). Edit the module's release version file `configure/CONFIG_module_VERSION` and the `Doxyfile`s in the top-level and/or documentation directories. In these, set `DEVELOPMENT_FLAG` to 0 and remove `-dev` from the `PROJECT_NUMBER` string. Commit these changes (don't push). Tag the module: `git tag -m 'ANJ: Tag for EPICS 7.0.8.1' <module-version>` Update the git submodule on the Base-7.0 branch to the newly-tagged version, check the module's status matches the tag: `cd base-7.0/modules git add <module> git submodule status --cached` Don't commit the submodule updates yet. 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. Push commits and the new tag to the submodule's GitHub repository (assumed to be the `upstream` remote): `cd base-7.0/modules/<module> git push --follow-tags upstream master` After all submodules complete commit the submodule updates which were added for each submodule in step 4 above to the 7.0 branch (don't push). After committing, make sure that the output from `git submodule status --cached` only shows the appropriate version tags in the right-most parenthesized column with no `-n-gxxxxxxx` suffix.
| Release Manager | `git grep UNRELEASED` and insert the release version to any doxygen annotations that have a `@since UNRELEASED` comment. Commit (don't push). 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. Edit the headings in the Release Notes to show the appropriate version number and remove the warning about this being an unreleased version of EPICS. 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.8.1` Don't push to GitHub 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". Set up the headings in the Release Notes for the next release version number and restore the warning about this being an unreleased version of EPICS. 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.8.1 ../base-7.0.8.1.tar.gz base-7.0.8.1/` Create a GPG signature file of the tarfile as follows: `cd .. gpg --armor --sign --detach-sig base-7.0.8.1.tar.gz`
| Release Manager | Test the tar file by extracting its contents and building it on at least one supported platform. If this succeeds the commits and new git tag can be pushed to the GitHub repository's 7.0 branch (assumed to be the `upstream` remote): `git push --follow-tags upstream 7.0`
Publish to epics.anl.gov
| Website Editor | Copy the tarfile and its signature to the Base download area of the website.
| Website Editor | Update the website subdirectory that holds the release documentation, and copy in the files from the base/documentation directory of the tarfile.
| Website Editor | Update the webpage for the new release with links to the release documents and tar file.
| Website Editor | Add the new release tar file to the website Base download index page.
| Website Editor | Link to the release webpage from other relevent areas of the website - update front page and sidebars.
| Website Editor | Add an entry to the website News page, linking to the new version webpage.
Publish to epics-controls.org
| Website Editor | Upload the tar file and its `.asc` signature file to the epics-controls web-server. `scp base-7.0.8.1.tar.gz base-7.0.8.1.tar.gz.asc epics-controls:download/base`
| Website Editor | 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 GitHub
| Release Manager | Go to the GitHub Create release from tag R7.0.8.1 page. Upload the tar file and its `.asc` signature file to the new GitHub release page.
| Release Manager | We used to close out bug reports in Launchpad at release-time, this would be the time to do that if we have an equivalent on GitHub.
Make Announcement
| Release Manager | Announce the release on the tech-talk mailing list.