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. Regenerate the Build Matrix

Run the matrix generator script to define combinations of Python and MPI:

cd recipes/e3sm-unified/configs
rm *.yaml
python generate.py

This produces matrix files like:

mpi_mpich_python3.10.yaml
mpi_hpc_python3.10.yaml

4. Edit `build_package.bash`

Update the channel list to include dev labels for any packages still in RC form. For example:

channels="-c conda-forge/label/chemdyg_dev \
         -c conda-forge/label/e3sm_diags_dev \
         -c conda-forge/label/mache_dev \
         -c conda-forge/label/mpas_analysis_dev \
         -c conda-forge/label/zppy_dev \
         -c conda-forge/label/zstash_dev \
         -c conda-forge"

Then define which matrix files to test. For example:

for file in configs/mpi_mpich_python3.10.yaml configs/mpi_hpc_python3.10.yaml
do
  conda build -m $file --override-channels $channels .
done

Make sure:

You use --override-channels to isolate testing to dev packages
You only include dev labels for packages with RCs — use stable versions otherwise

5. Build and Troubleshoot

Run the script:

bash build_package.bash

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

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

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

8. 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

Fork the e3sm-unified-feedstock
Create a new branch in your fork (e.g., update-1.12.0rc1)
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.
Open a PR from your fork → dev branch on the feedstock
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