Creating RCs for Dependency Packages

This page describes how to create release candidates (RCs) for packages that are included in the E3SM-Unified environment, such as e3sm_diags, mpas-analysis, zppy, and zstash.

We use e3sm_diags as a concrete example, but the process is similar for all E3SM-developed dependencies.

Step-by-Step: Creating an RC for e3sm_diags

1. Tag a Release Candidate in the Source Repo

Go to the source repository: E3SM Diags GitHub

Create a release tag:

git checkout main
git fetch --all -p
git reset --hard origin/main
git tag v3.0.0rc1
git push origin v3.0.0rc1

Note:

  • e3sm_diags uses a v prefix in version tags (e.g., v3.0.0rc1) as part of its established convention.

  • For new packages, it’s recommended to follow Semantic Versioning and omit the v prefix (i.e., tag as 3.0.0rc1).

2. Prepare the Feedstock PR

Go to the conda-forge feedstock for e3sm_diags: E3SM Diags Feedstock

If a dev branch does not already exist:

  • Clone the feedstock repo locally

  • Create a new branch off main called dev

  • Push it to the origin

    Note: By making no changes from the main branch, you ensure that no new packages will be created when you push the dev branch to the origin

3. Fork the Feedstock and Create a PR

  1. Fork the feedstock repo to your GitHub account.

  2. In your fork, create a new branch (e.g., update-v3.0.0rc1).

    Important: Do not create branches directly on the main conda-forge feedstock. All changes should go through a pull request from your personal fork. Creating a branch on the main feedstock can trigger package builds before your updates have been properly tested or reviewed. (e.g., update-v3.0.0rc1).

  3. Edit recipe/meta.yaml:

  • Update the version field to match your RC tag (e.g., v3.0.0rc1)

  • Set the sha256 hash. To determine the hash, you need to download the source file on a Linux (e.g. HPC) machine and run sha256sum on it. For some reason, Macs seem to produce an incorrect hash.

  • Update dependencies if needed (e.g., pin to RC versions of other tools)

  1. If you created the dev branch above and no previous release candidates have been added, you will need to add recipe/conda_build_config.yaml with contents like:

    channel_targets:
  - conda-forge e3sm_diags_dev

    The label is the name of the package with any - replaced by _, followed by _dev.

  2. Commit the changes and push them to the branch on your fork (unless editing on GitHub directly).

  3. Open a pull request:

    • Source: your RC branch on your fork (head repository)

    • Target: the dev branch on the conda-forge feedstock (base repository)

4. Merge the PR Once CI Passes

After CI completes successfully:

  • Review the logs if needed

  • Merge the PR into the dev branch

The RC build will now be published to:

conda-forge/label/e3sm_diags_dev

You can test the RC by installing it like so:

conda install -c conda-forge/label/e3sm_diags_dev e3sm_diags

Summary

Creating an RC for a dependency involves:

  1. Tagging the source repository

  2. Opening a PR on the feedstock targeting the dev branch

  3. Waiting for CI to pass, then merging

This process enables E3SM-Unified maintainers to incorporate the RC version of your package into a unified test build.

➡ Next: Creating an RC for E3SM-Unified