Creating an RC for E3SM-Unified

Once release candidates (RCs) of core E3SM packages (like e3sm_diags, mpas-analysis, etc.) have been published, an RC version of the E3SM-Unified metapackage can be built and tested.

This guide walks through creating a release candidate of e3sm-unified based on those RC dependencies.

1. Create a Branch for the New Version

Create a feature branch on your fork of e3sm-unified, typically called:

update-to-<version>

Example:

git checkout -b update-to-1.12.0

2. Update the Conda Recipe

Edit recipes/e3sm-unified/meta.yaml:

  • Update the version field to match the RC version (e.g., 1.12.0rc1)

  • Update the list of dependencies and versions, including RCs

  • Be sure to include the correct version for each core tool (e.g., e3sm_diags, mpas-analysis, etc.)

3. Run build_packages.py

If you are building packages for an RC version of E3SM-Unified, the script will build packages for Python 3.10 and the nompi and hpc versions of MPI by default (those needed for login and compute nodes, respectively, on HPC). You may wish to use the --python and --mpi flags to override these.

You should supply the --conda flag if not using ~/miniforge3.

./build_packages.py --conda ~/minforge3 --python 3.10 --mpi nompi hpc

The script will produce a matrix of files like:

  • configs/mpi_nompi_python3.10.yaml

  • configs/mpi_hpc_python3.10.yaml

These are then used by conda build to build the appropriate variant of the conda package.

4. Troubleshoot

If builds fail, consult the Troubleshooting Conda Build Failures guide. This includes how to use conda_first_failure.py to debug dependency resolution issues.

5. Make a draft PR

Push the branch to your fork of e3sm-unified and make a draft PR to the main e3sm-unified repo. Use that PR to document progress and highlight important version updates in this release for the public (those without acces to E3SM’s Confluence pages). See this example.

6. Keeping updated on Confluence

As deployment and testing progresses, you needs to make sure that the packages in your update-to-<version> branch match the agreed-upon versions on Confluence. Maintainers of dependencies will need to inform you as new release candidates or final releases become available, preferably by updating Confluence and also sending a Slack message or email.

As testing nears completion, it is also time to draft a release note, similar to this example. Ask maintainers of any of the main E3SM-Unified packages that have been updated since the last release to describe (briefly and with minimal jargon) what is new in their package that would be of interest to users.

7. Tag and Publish the RC

After test builds are successful:

Tag a Release Candidate

Tag your update-to-<version> branch in the e3sm-unified repo:

git checkout update-to-1.12.0
git tag 1.12.0rc1
git remote add E3SM-Project/e3sm-unified git@github.com:E3SM-Project/e3sm-unified.git
git fetch --all -p
git push E3SM-Project/e3sm-unified 1.12.0rc1

Create a Conda-Forge PR

  1. Fork the e3sm-unified-feedstock

  2. Create a new branch in your fork (e.g., update-1.12.0rc1)

  3. Edit recipe/meta.yaml:

    • Update the version field (e.g., 1.12.0rc1)

    • Update all dependencies to match the versions in your update-to-<version> branch of e3sm-unified repo

    ⚠️ Reminder: The feedstock’s meta.yaml is the authoritative source for the Conda package. The one in the e3sm-unified repo is for testing and provenance only.

  4. Open a PR from your fork → dev branch on the feedstock

  5. Merge once CI passes

The RC package will now be available under the label:

conda-forge/label/e3sm_unified_dev

It’s ready to be tested and deployed on HPC systems.

➡ Next: Deploying on HPCs for Testing