From d2c73046f47c7f6da23ee1a07019dccefeb324a8 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 29 Apr 2025 12:30:39 -0500 Subject: [PATCH] Updated Release Checklist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Includes instructions on how to generate a new Release-.md file at the right time during the release process – it won't work properly if done earlier. --- documentation/ReleaseChecklist.html | 254 ++++++++++++++++------------ 1 file changed, 142 insertions(+), 112 deletions(-) diff --git a/documentation/ReleaseChecklist.html b/documentation/ReleaseChecklist.html index 40f6d5808..6381c190b 100644 --- a/documentation/ReleaseChecklist.html +++ b/documentation/ReleaseChecklist.html @@ -52,8 +52,6 @@ everything that has to be done since it's so easy to miss steps.

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
@@ -91,13 +89,16 @@ everything that has to be done since it's so easy to miss steps.

  - Release Manager
+ Release Manager
& all developers - Ensure that documentation will be updated before the release date: + Request that documentation be updated and information about new + features be added before the release date: @@ -113,16 +114,7 @@ everything that has to be done since it's so easy to miss steps.

  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. + Run the internal test programs on all appropriate platforms.   @@ -132,19 +124,6 @@ everything that has to be done since it's so easy to miss steps.

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 @@ -152,7 +131,9 @@ everything that has to be done since it's so easy to miss steps.

@@ -173,59 +154,53 @@ everything that has to be done since it's so easy to miss steps.

Release Manager -

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

+

For each external submodule to be tagged

    -
  1. git grep UNRELEASED and insert the module version to any - doxygen annotations that have a @since UNRELEASED comment. +
  2. cd base-7.0/modules/<module>; git grep UNRELEASED + and insert the submodule's version number into any doxygen + annotations that have a @since UNRELEASED comment. Commit (don't push yet).
    3. -
  3. 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. - Commit these changes (don't push).
    4. +
  4. Check that the submodule's Release Notes have been updated to + cover all changes; add missing items as necessary, and set the + module version number and release date if appropriate.
    + Commit the changes to the submodule's Notes file (don't push).
    5. + +
  5. Copy the new submodule version number and Release Notes entries + into a new file named module-release in the + base-7.0/documentation/new-notes directory.
  6. Edit the module's release version file configure/CONFIG_module_VERSION and the Doxyfiles in the top-level and/or documentation - directories. In these, set DEVELOPMENT_FLAG to 0 and remove + directories. In these, set DEVELOPMENT_FLAG=0 and remove -dev from the PROJECT_NUMBER string. Commit these changes (don't push):
    - git ci -m 'Final commit for <module-version>' + git commit -m 'Final commit for <submodule-version>'
    7. -
  7. Tag the module: +
  8. Tag the submodule:
    - git tag -m 'ANJ: Tag for EPICS 7.0.8.2' <module-version> + git tag -m 'ANJ: Tag for EPICS 7.0.9.1' <submodule-version>
    9. -
  9. Generate documentation or Release Notes using one of these: -
      -
    • For older modules with a RELEASE_NOTES.md file convert it to - HTML and view in a browser to check the formatting as follows: -
      - cd base-7.0/modules/<module>/documentation
      - pandoc -f gfm -t html -o RELEASE_NOTES.html RELEASE_NOTES.md -
      +
    • Generate documentation for modules with release_notes.dox + files. Prepare to update the github-pages website as follows: +
      + cd base-7.0/modules/<module>/documentation
      + make commit
      + git push --force upstream gh-pages +
      + Q: Delay this git push until later?
      • -
    • For newer modules with release_notes.dox file, generate the - new github-pages website as follows: -
      - cd base-7.0/modules/<module>/documentation
      - make commit - git push --force upstream gh-pages -
      - Q: Delay this git push until later?
      • -
    10. - -
  10. Update the git submodule on the Base-7.0 branch to the +
  11. 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>
    + cd base-7.0/modules
    + git add <module>
    git submodule status --cached
    Don't commit the submodule updates yet. @@ -241,18 +216,41 @@ everything that has to be done since it's so easy to miss steps.

  12. Push commits and the new tag to the submodule's GitHub repository (assumed to be the upstream remote):
    - cd base-7.0/modules/<module>
    + cd base-7.0/modules/<module>
    git push --follow-tags upstream master
    13. +
+ + + + Release Manager + +

After all submodules have been updated:

+
    + +
  1. Commit the submodule updates which were added for each submodule + in step 7 above to the 7.0 branch (don't push): +
    + cd base-7.0/modules
    + git commit -m "Update git submodules for release" +
    2. + +
  2. 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.
    3. + +
  3. Add and commit the new Release Note entry files that were created + for each submodule in step 3 above (don't push): +
    + cd base-7.0/documentation
    + git add new-notes
    + git commit -m "Add submodule release note entries" +
    4. +
-

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.

@@ -260,35 +258,62 @@ everything that has to be done since it's so easy to miss steps.

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).

+

In the main epics-base repository

+
    +
  1. cd base-7.0; git grep UNRELEASED and insert the release + version to any doxygen annotations that have a + @since UNRELEASED comment. Commit (don't push).

    + +
  2. Edit the main EPICS Base version file and the built-in module + version files:
    3. +
      +
    • configure/CONFIG_BASE_VERSION
      • +
    • configure/CONFIG_LIBCOM_VERSION
      • +
    • configure/CONFIG_CA_VERSION
      • +
    • configure/CONFIG_DATABASE_VERSION
      • +
    + +
  3. 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 will have + been incremented immediately after the previous release tag was + applied. Set all DEVELOPMENT_FLAG values to 0 and + EPICS_DEV_SNAPSHOT to the empty string.
    4. + +
  4. Commit the above changes (don't push): +
    + cd base-7.0
    + git add configure/CONFIG_*_VERSION
    + git commit -m "Set core version numbers for release" +
    + +
  5. Run these commands to generate the RELEASE-7.0.9.1.md + file and remove the individual release note entry files from + documentation/new-notes: +
    + cd base-7.0/documentation
    + make release +
    + The make recipe adds and removes files from the Git index but + doesn't commit the changes itself. Run these commands to confirm + that it succeeded and commit the result: +
    + git status
    + git diff --staged
    + git commit -m "Generate RELEASE-7.0.9.1.md" +
    +
    6. +
+ Release Manager Tag the epics-base module in Git:
- cd base-7.0
- git tag -m 'ANJ: Tagged for release' R7.0.8.2 + cd base-7.0
+ git tag -m 'ANJ: Tagged for release' R7.0.9.1

Don't push to GitHub yet.

@@ -296,7 +321,8 @@ everything that has to be done since it's so easy to miss steps.

Release Manager - Edit the main EPICS Base version file and the built-in module version +

After tagging the release

+ Edit the main EPICS Base version file and the built-in module version files:
  • configure/CONFIG_BASE_VERSION
    • @@ -321,13 +347,13 @@ everything that has to be done since it's so easy to miss steps.

    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.2 ../base-7.0.8.2.tar.gz base-7.0.8.2/ + cd base-7.0
    + ./.tools/make-tar.sh R7.0.9.1 ../base-7.0.9.1.tar.gz base-7.0.9.1/
    Create a GPG signature file of the tarfile as follows:
    - cd ..
    - gpg --armor --sign --detach-sig base-7.0.8.2.tar.gz + cd ..
    + gpg --armor --sign --detach-sig base-7.0.9.1.tar.gz
    @@ -355,9 +381,15 @@ everything that has to be done since it's so easy to miss steps.

    Website Editor - Update the website subdirectory that holds the release - documentation, and copy in the files from the base/documentation - directory of the tarfile. + Add the new release tar file to the website Base download index + page. + + + + Website Editor + Create or update the website subdirectory that holds the release + documentation, and copy in the files to be published with this + release version. @@ -365,12 +397,6 @@ everything that has to be done since it's so easy to miss steps.

    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 @@ -393,20 +419,23 @@ everything that has to be done since it's so easy to miss steps.

    Upload the tar file and its .asc signature file to the epics-controls web-server.
    - scp base-7.0.8.2.tar.gz base-7.0.8.2.tar.gz.asc epics-controls:download/base
    + scp base-7.0.9.1.tar.gz base-7.0.9.1.tar.gz.asc epics-controls:download/base
    Website Editor - Follow instructions on +

    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. - + the Html Snippet for the series download.

    +

    Not covered in those instructions: Go to Posts, find a previous + release and use "Duplicate Post", then edit the result and publish it. + This generates the News item. +

    @@ -416,10 +445,11 @@ everything that has to be done since it's so easy to miss steps.

    Release Manager Go to the GitHub - - Create release from tag R7.0.8.2 page. + + Create release from tag R7.0.9.1 page. Upload the tar file and its .asc signature file to the new - GitHub release page. + GitHub release page, or just drag-n-drop them into the page. + Copy/paste the text from the previous release and edit. Submit.