Releasing a New Version

This document describes the steps for maintainers to tag and release a new version of mpas_tools, and to update the conda-forge feedstock.

Version Bump and Dependency Updates

  1. Update the Version Number

    • Open a pull request (PR) to update the version number in the following two files: - conda_package/mpas_tools/__init__.py - conda_package/recipe/meta.yaml

    • Make sure the version follows [semantic versioning](https://semver.org/). For release candidates, use versions like 1.3.0rc1 (no v prefix).

  2. Check and Update Dependencies

    • Ensure that dependencies and their constraints are up-to-date and consistent in: - conda_package/recipe/meta.yaml (dependencies for the conda-forge

      release)

      • conda_package/pyproject.toml (dependencies for PyPI; used as a sanity check)

      • conda_package/dev-spec.txt (development dependencies; should be a superset of those for the conda-forge release)

    • The dependencies in meta.yaml are the ones that will be used for the released package on conda-forge. The dependencies in pyproject.toml are for PyPI and should be kept in sync as much as possible but are only there as a sanity check when we run `pip check. The dev-spec.txt file should include all dependencies needed for development and testing.

    • Review and update dependency versions and constraints as needed.

  3. Make a PR and merge it

Tagging and Publishing a Release Candidate

  1. Tagging a Release Candidate

    • For release candidates, do not create a GitHub release page. Just create a tag from the command line:

      • Make sure your changes are merged into master (or your update branch) and your local repo is up to date.

      • Tag the release candidate (e.g., 1.3.0rc1):

        git checkout master
git fetch --all -p
git reset --hard origin/master
git tag 1.3.0rc1
git push origin 1.3.0rc1

        (Replace 1.3.0rc1 with your actual version, and master with your branch if needed.)

      Note: This will only create a tag. No release page will be created on GitHub.

  2. Updating the conda-forge Feedstock for a Release Candidate

    • The conda-forge feedstock does not update automatically for release candidates.

    • You must always create a PR manually, and it must target the dev branch of the feedstock.

    Steps:

    • Download the release tarball:

      wget https://github.com/MPAS-Dev/MPAS-Tools/archive/refs/tags/<version>.tar.gz

    • Compute the SHA256 checksum:

      shasum -a 256 <version>.tar.gz

    • In the meta.yaml of the feedstock recipe: - Set {% set version = "<version>" %} - Set the new sha256 value - Update dependencies if needed

    • Commit, push to a new branch, and open a PR against the ``dev`` branch of the feedstock: https://github.com/conda-forge/mpas_tools-feedstock

    • Follow any instructions in the PR template and merge once approved

Publishing a Stable Release

  1. Publishing a Stable Release

    • For stable releases, create a GitHub release page as follows:

      • Go to https://github.com/MPAS-Dev/MPAS-Tools/releases

      • Click “Draft a new release”

      • Enter a tag (e.g., 1.3.0; do not include a v in front)

      • Set the release title to the version prefixed with v (e.g., v1.3.0)

      • Generate or manually write release notes

      • Click “Publish release”

  2. Updating the conda-forge Feedstock for a Stable Release

    Note: If you are impatient, you can accelerate this process by creating a bot issue at: https://github.com/conda-forge/mpas_tools-feedstock/issues with the subject @conda-forge-admin, please update version. This will open a new PR with the version within a few minutes.

    • If the bot PR does not appear or is too slow, you may update manually (see the manual steps for release candidates above, but target the main branch of the feedstock).

Post Release Actions

  1. Verify and Announce

    • Install the package in a clean environment to test:

      conda create -n test-mpas-tools -c conda-forge mpas_tools=<version>

    • Optionally announce the release on relevant communication channels

    • Update any documentation or release notes as needed