Skip to content

Release Procedure

Jump to bottom
Gerhard Theurich edited this page Nov 13, 2024 · 112 revisions

Versioning

Beginning with version 8.0.0, ESMF uses semantic versioning with the format: MAJOR.MINOR.PATCH

  • MAJOR release increments indicate substantial new capabilities or, in rare cases, backward incompatibility
  • MINOR release increments indicate addition of backward compatible features
  • PATCH release increments indicate backward compatible bug fixes

Major/Minor Release Procedure

  1. Taking Stock, Release Notes, Punch List
  • Add a new tab "X.Y.0" under the "Taking Stock" spreadsheet: https://docs.google.com/spreadsheets/d/1jrW6YKMAXHonPtFIQqgf1xYz271BhvSdyg0LYxyN7D8/edit#gid=671239475
  • Every developer that has made contributions to ESMF since the last release, that either have been merged into the develop branch or are close to being ready for merge into develop, fills in the current status into the shared spreadsheet.
  • There should be one line per major contribution, with columns for the associated Release Note and the current status.
  • The current status entry needs to have enough details to indicate whether the feature is either completed, or is only partially completed but usable, or not yet usable at all. It should further indicate how much work is still needed for full completion.
  • A call is scheduled with all contributing developers to review the status spreadsheet. Rows are marked in a way to allow the spreadsheet to be used as a punch list for guidance in wrapping up the release.
  • The time table for the release is planned out and posted below.
  1. Cut Freeze
  • The last date by which to merge development work into develop branch for release X.Y.0.
  • From this point on, until after the release branch cut when develop branch is unfrozen:
    • Only fixes, tests, and documentation changes go into develop branch - no new development!
    • All pushes to develop require prior core discussion, preferably via PR.
  • Regular nightly testing continues on develop. Developers monitor the results daily and fix any major issues. The goal is to ensure develop is suitable for cutting the release branch. This stage should take a maximum of one week.
  • This is also the time to take care of the following code clean-up actions:
    • Look for DEBUG messages in any of the PET* files created by UTest, STests, and Examples. Disable any sections of code that generate DEBUG messages.
    • Look for and remove any debugging timing regions inside ESMF profiles in the nuopc-app-prototypes.
  1. Branch Cut
  • The develop branch is tagged one last time with a snapshot for release X.Y.0. All further X.Y.0 snapshot tags on the release branch.
  • Release branch release/X.Y.0 is created from develop.
  • The develop branch is immediately unfrozen and development work toward the next release (X.Y+1.0) commences.
    • Versioning on develop is incremented in all the appropriate files:
      • src/Infrastructure/Util/include/ESMC_Macros.h
      • src/Infrastructure/Util/src/ESMF_UtilTypes.F90
      • src/doc/ESMF_usrdoc.ctex
      • src/doc/ESMF_refdoc.ctex
      • src/doc/ESMC_crefdoc.ctex
      • src/addon/NUOPC/doc/NUOPC_howtodoc.ctex
      • src/addon/NUOPC/doc/NUOPC_refdoc.ctex
      • src/addon/esmpy/pyproject.toml
  • Same procedure for https://github.com/esmf-org/nuopc-app-prototypes and https://github.com/esmf-org/esmf-extended-tests.
  • Nightly testing for the release/X.Y.0 branch is enabled (in addition to develop) under all machine configurations at https://github.com/esmf-org/esmf-test-scripts/tree/main/config
  • Check test coverage:
    • Run the Test Coverage GitHub Action, selecting the release branch.
    • Download the generated artifacts from the workflow instance, and inspect for uncovered methods.
    • If there are any ESMF or ESMC methods not tested, add items for them onto the "Taking Stock" sheet to be dealt with.
  • A first version of the API-change sheet is compiled:
  1. Active Release Branch Work and Testing
  • Nightly artifact generation (see end of page) is activated for release/X.Y.0 branch.
  • Developers continue fixing outstanding issues indicated by regression testing, “Public API Not Tested” reports, and documentation builds.
  • Work as per the release punch list, compiled during step 0, is ongoing. All commits are now to the release branch. The punch list is updated (daily) according to progress.
  1. API Change Spreadsheet
  1. Release Notes and Known Issues
  • A google doc is created to collect and review Release Notes (RNs) and Known Issues (KIs).
  • The KIs are compiled based on the nightly reports.
  • The RNs are compiled from the original status / punch list spread sheet where developers provided a draft of the wording.
  • A call is scheduled with all contributing developers to review RNs and KIs.
  • RNs and KIs are listed on the GitHub release tag page (example), added to the master list of all releases (see how to change the ESMF web site). Also sent out to the esmf_info email list during Release Announcement, see below.
  • The "Docs to Markdown" Google Doc Add-on provides a convenient way to convert and copy sections (with active links, etc.) from the google doc (RNs, KIs) to HTML and MD.
  1. Applications Testing
  • A spreadsheet is created, listing all of the applications available for testing, and the associated team member.
  • A snapshot tag on the release branch is identified as the release candidate.
  • Applications are tested with the release candidate tag.
  • Any issues encountered during applications testing are discussed on core. This might trigger an effort to fix the issue, leading to an updated release candidate. Alternatively it might be carried as a known bug for this release.
  1. ESMPy
  • We are now depending on nightly testing of ESMPy.
  • Read and update the ESMPy README and init.py.
  • Search for html links to update.
  • Update the "Installation" section of the documentation to use the current release tag.
  • (NOTE: See ESMPy release procedure: https://github.com/esmf-org/esmf/wiki/ESMPy-Release-Procedure)
  1. Update Versioning and Bundled Documentation
  • Put a "last" beta snapshot tag on release/X.Y.0 branch. This is a good point to merge changes back to develop.
  • Change all versioning in code and docs to indicate X.Y.0 without snapshot suffix. The affected files are:
    • src/Infrastructure/Util/include/ESMC_Macros.h
    • src/Infrastructure/Util/src/ESMF_UtilTypes.F90
    • src/doc/ESMF_usrdoc.ctex
    • src/doc/ESMF_refdoc.ctex
    • src/doc/ESMC_crefdoc.ctex
    • src/addon/NUOPC/doc/NUOPC_howtodoc.ctex
    • src/addon/NUOPC/doc/NUOPC_refdoc.ctex
  • This affects Fortran and C refdoc, userdoc, and NUOPC refdoc.
  • Make sure all the ESMPy changes required for the release are made under src/addon/esmpy.
  1. Merge into 'main' and Release Tag
  • Branch release/X.Y.0 is merged into main using "-s theirs" strategy for https://github.com/esmf-org/esmf. Branch main is tagged with the official release tag vX.Y.0. Use annotated tag: tag -a vX.Y.0 with commit message Release X.Y.0.
  • Branch release/X.Y.0 is merged into main using "-s theirs" strategy for https://github.com/esmf-org/nuopc-app-prototypes. Branch main is tagged with the official release tag vX.Y0. Use annotated tag: tag -a vX.Y.0 with commit message Release X.Y.0.
  • Branch release/X.Y.0 is merged into main using "-s theirs" strategy for https://github.com/esmf-org/esmf-extended-tests. Branch main is tagged with the official release tag vX.Y.0. Use annotated tag: tag -a vX.Y.0 with commit message Release X.Y.0.
  • Note that Git does not actually offer the "-s theirs" strategy, but it can be carried out manually via this sequence: 
      git checkout main
  git pull -p
  git merge --no-commit -s ours release/X.Y.0
  git rm -rf .
  git checkout release/X.Y.0 -- .
  git commit
  1. Release Tag Testing and Collection
  • Switch nightly testing from release branch to release tag.
  • Create a new platforms_X_Y_0.md table under esmf-org.github.io/_pages.
  • Basic applications testing is repeated with the release tag. (OPTIONAL!)
  • There could be a delay between the release tag on the main branch, and collecting all the final summary test reports to populate the table. The official release date is determined by sending out the release announcement through the esmf_info list (see item below).
  • Generate the ESMPy documentation and add to the esmpy_doc repo.
  • The tag on main should trigger the builds of esmf_feedstock and esmpy_feedstock for the ESMPy conda-forge package build, verify this was built successfully.
  1. Release under GitHub
  1. Update Web Pages
  1. Release Announcement
  • The release announcement email is written and reviewed.
  • Contents of the release announcement is also posted under the GitHub release page for https://github.com/esmf-org/esmf
  • The release announcement email is sent out to esmf_info.
  1. Final Merge Back
  • Merge appropriate changes from release/X.Y.0 back to develop (for both esmf and nuopc-app-prototypes repos).
  • Changes are expected to be merged from release/X.Y.0 to develop throughout the release process. This is the final check to make sure nothing was missed.

Patch Release Procedure

  1. Patch Branch Cut
  • Patch branch patch/X.Y.Z is created from main, starting at release tag vX.Y.0.
  • Cherry-pick relevant fixes already made under develop.
  • Bump versioning into X.Y.Z beta snapshot phase, and tag as vX.Y.Zb00.
  1. Active Patch Branch Testing
  • Nightly artifact generation (see end of page) is activated for patch/X.Y.Z.
  • Check test coverage:
    • Run the Test Coverage GitHub Action, selecting the patch branch.
    • Download the generated artifacts from the workflow instance, and inspect for uncovered methods.
    • If there are any ESMF or ESMC methods not tested, add items for them onto the "Taking Stock" sheet to be dealt with.
  • A first version of the API-change sheet is compiled:
  1. Patch Work
  • Developers merge fixes from develop branch or implement on patch/X.Y.Z.
  • Any fix implemented directly on patch/X.Y.Z must be considered for back merging into develop.
  1. Follow "Major/Minor Release Procedure" starting with item #4.
  • Release tag vX.Y.Z goes directly on patch/X.Y.Z branch.
  • Use annotated tag: tag -a vX.Y.Z with commit message Patch Release X.Y.Z.
  • There is no merge onto main branch.

Nightly Artifact Generation

The release procedures outlined above assume that the following artifacts are generated nightly on develop, and can easily be set to (in addition to develop) be generate for any other branch:

  • Library regression test reports across a set of test platforms.
  • NUOPC prototype regression test reports across a set of test platforms.
  • RegridWeightGen with BFB regression test reports across a set of test platforms. For this the RegridWeightGen used should be from extended-tests tag of the previous release. This version of the RegridWeightGen is then used (1) to generated the baseline weight files using an ESMF installation with the previous release tag, and (2) the new release weight files with an ESMF installation with the new release tag.

To activate/deactivate specific branches for each of the nightly testing platforms, edit the respective *.yaml file under https://github.com/esmf-org/esmf-test-scripts/tree/main/config. Changes pushed to this repo will be picked up automatically by each platform.

GitHub Actions Generated Artifacts

These artifacts are generated via GitHub Actions.

Releases Time Table

Release/Phase proposed date actual date tag
8.8.0
Taking Stock 12/04/24 https://github.com/orgs/esmf-org/projects/14/views/2?sliceBy%5Bvalue%5D=8.8
Cut Freeze 12/06/24
API review 12/11/24
Branch Cut 12/12/24
Last Beta Tag 01/06/25
Release Tag 01/08/25
Release 01/09/25
8.7.0
Taking Stock ? ? (Used a more continuous project board approach so there wasn't really a start date.)
Cut Freeze 06/30/24 08/07/24 09/11/24 09/11/24 v8.7.0b14
Branch Cut 07/07/24 08/14/24 09/16/24 09/16/24 v8.7.0b14
Last Beta Tag 07/14/24 08/21/24 10/03/24 10/03/24 v8.7.0b15
Release Tag 07/21/24 08/28/24 10/03/24 10/03/24 v8.7.0
Release 08/15/24 09/04/24 10/07/24
8.6.0
Taking Stock 09/21/23 09/27/23
Cut Freeze 09/28/23 10/05/23 10/12/23 10/20/23 10/24/23 v8.6.0b11
Branch Cut 10/05/23 10/12/23 10/19/23 10/26/23 10/27/23 v8.6.0b13
Last Beta Tag 10/12/23 10/19/23 10/26/23 11/02/23 11/08/23 v8.6.0b15
Release Tag 10/19/23 10/26/23 11/02/23 11/09/23 11/09/23 v8.6.0
Release 10/26/23 11/02/23 11/09/23 11/16/23 11/14/23 v8.6.0
8.5.0
Taking Stock 03/23/23 04/20/23 05/03/23 05/03/23
Cut Freeze 03/30/23 04/27/23 05/25/23 06/15/23 06/28/23 v8.5.0b25
Branch Cut 04/06/23 05/04/23 06/08/23 06/22/23 07/05/23 07/11/23 v8.5.0b27
Last Beta Tag 04/13/23 05/11/23 06/15/23 06/29/23 07/14/23 07/24/23 v8.5.0b28
Release Tag 04/20/23 05/18/23 06/22/23 07/06/23 07/18/23 07/25/23 v8.5.0
Release 04/27/23 05/25/23 06/29/23 07/13/23 07/20/23 07/26/23 v8.5.0
8.4.2
Release 04/25/23 04/25/23 v8.4.2
8.4.1
Release 03/06/23 03/06/23 v8.4.1
8.4.0
Cut Freeze 09/29/22 10/03/22 v8.4.0b17
Branch Cut 10/06/22 10/15/22 v8.4.0b20
Last Beta Tag 10/13/22 10/20/22 10/23/22 v8.4.0b21
Release Tag 10/20/22 10/27/22 10/24/22 v8.4.0
Release 10/27/22 11/03/22 10/28/22 v8.4.0
8.3.1
Release 09/20/22 09/21/22 v8.3.1
8.3.0
Cut Freeze 03/17/22 03/24/22 05/18/22 05/18/22 v8.3.0b16
Branch Cut 03/24/22 03/31/22 05/20/22 05/19/22 v8.3.0b16
Last Beta Tag 03/31/22 04/07/22 05/31/22 06/03/22 v8.3.0b17
Release Tag 04/07/22 04/12/22 06/02/22 06/06/22 v8.3.0
Release 04/14/22 06/03/22 06/08/22 v8.3.0
8.2.0
Cut Freeze 10/05/21 10/01/21 ESMF_8_2_0_beta_snapshot_21
Branch Cut 10/07/21 10/05/21 ESMF_8_2_0_beta_snapshot_21
Last Beta Tag 10/20/21 10/21/21 ESMF_8_2_0_beta_snapshot_23
Release Tag 10/14/21 10/21/21 10/25/21 10/26/21 ESMF_8_2_0
Release 10/21/21 10/28/21 10/28/21 ESMF_8_2_0
8.1.1
Release 04/23/21 04/23/21 ESMF_8_1_1
8.1.0
Cut Freeze 02/11/21 02/15/21 02/15/21 ESMF_8_1_0_beta_snapshot_46
Branch Cut 02/18/21 02/18/21 ESMF_8_1_0_beta_snapshot_47
Release Tag 03/04/21 03/11/21 03/18/21 03/23/21 ESMF_8_1_0
Release 03/18/21 03/25/21 03/29/21 ESMF_8_1_0
8.0.1
Soft Freeze 04/16/20 04/16/20
Hard Freeze 04/23/20 04/30/20
Tag Freeze 05/07/20 05/15/20 ESMF_8_0_1
Release 05/21/20 05/21/20 ESMF_8_0_1
8.0.0
Soft Freeze 07/25/19 07/30/19 07/31/19 ESMF_8_0_0_beta_snapshot_42
Hard Freeze 08/22/19 08/29/19 08/30/19 ESMF_8_0_0_beta_snapshot_48
Tag Freeze 09/05/19 09/12/19 09/19/19 09/26/19 10/03/19 ESMF_8_0_0
Release 09/19/19 09/26/19 10/03/19 10/10/19 10/15/19 ESMF_8_0_0
7.1.0r
Soft Freeze 01/25/18 02/01/18 02/04/18 ESMF_7_1_0_beta_snapshot_50
Hard Freeze 02/08/18 02/15/18 02/20/18 02/23/18 ESMF_7_1_0_beta_snapshot_53
Tag Freeze 02/22/18 03/01/18 03/06/18 03/06/18 ESMF_7_1_0r
Release 03/01/18 03/08/18 03/08/18 ESMF_7_1_0r

Developers Guide

Clone this wiki locally