Skip to content

make_release.md

Latest commit

 

History

History
152 lines (96 loc) · 7.51 KB

make_release.md

File metadata and controls

152 lines (96 loc) · 7.51 KB
Raw

Releasing FloPy

Steps

The FloPy release procedure is largely automated with GitHub Actions in release.yml, but there are a few manual steps.

A local development environment is assumed in this document.

To make a release,

  1. Update citations
  2. Review deprecations
  3. Regenerate MF6 module
  4. Create a release branch
  5. Merge release branch to master
  6. Publish the release
  7. Reset the develop branch

Update citations

Update the authors in CITATION.cff for the Software/Code citation for FloPy, if required.

Review deprecations

If this is a patch release, skip this step. If this is a minor or major release, review deprecation warnings. Correct any deprecation version numbers if necessary — for instance, if the warning was added in the latest development cycle but incorrectly anticipated the forthcoming release number (e.g., if this release was expected to be minor but was promoted to major). If any deprecations are due this release, remove the corresponding features. FloPy loosely follows NEP 23 deprecation guidelines: removal is recommended after at least 1 year or 2 non-patch releases.

To search for deprecation warnings with git: `git grep [-[A/B/C]N] <pattern>`, where N is the optional number of extra lines of context and A/B/C selects post-context/pre-context/both, respectively. Some terms to search for:

- deprecated
- .. deprecated::
- DEPRECATED
- DeprecationWarning
- FutureWarning

Regenerate MF6 module

The flopy.mf6.modflow module must be regenerated to match the latest MF6 version's input specification.

python -m flopy.mf6.utils.generate_classes --releasemode

The --releasemode flag omits developmode variables from generated modules.

Create a release branch

Create a release branch from develop. The release branch name should be the version number with a v prefix (e.g. v3.3.6), with an optional rc suffix.

Pushing the release branch to the repository triggers the workflow.

  • update version strings to match the version number in the release branch name
  • regenerate plugin classes from MODFLOW 6 DFN files
  • rerun tests and notebooks
  • generate and update changelogs
  • build and test the FloPy package

If the branch name ends with rc, it's a dry run and the workflow stops here. If the branch name does not end with rc the workflow creates a draft PR from the release branch into the master branch.

Note: the changelog is generated from commit messages with git-cliff. Development PRs are squash merged, so the PR title becomes that message, and a title that is not a conventional commit header is dropped from the notes without warning. .github/workflows/pull_request.yml rejects such titles, but it cannot tell whether the type is the right one: a user facing change titled chore: still passes the check and is still dropped. Review the generated changelog on the release PR and add anything missing to the section for the version being cut.

Merge release branch to master

Review the PR and merging if it passes inspection.

Note: the PR should be merged, not squashed. Squashing removes the commit history from the master branch and causes develop and master to diverge, which can cause future PRs updating master to replay commits from previous releases.

Merging the PR triggers a job to draft a release.

Publish the release

Review the release and publish it. Publishing the release triggers a final job to publish the flopy package to PyPI.

The release workflow assumes trusted publishing has been configured in the PyPI admin interface. A GitHub environment called release is required (however it needs no secrets or environment variables).

Note: PyPI matches a trusted publisher on the organization name, the repository name, the workflow filename and the environment name. Renaming any of them silently invalidates the publisher, and nothing reports it until the next release fails with invalid-publisher — possibly long after the rename. After any such rename, update the publisher at https://pypi.org/manage/project/flopy/settings/publishing/ to match.

For the Conda distribution, there is a bot which will automatically detect new package versions uploaded to PyPI and create a PR to update the conda-forge/flopy-feedstock repository. This PR can be reviewed, updated if needed, and merged to update the package on the conda-forge channel. If it becomes necessary to manually publish an update to conda forge, see below.

Note: the bot updates only the version number and the checksum. If the release changed FloPy's dependencies or minimum versions, update the recipe's host and run requirements to match the Requires-Dist metadata of the sdist on PyPI before merging. A maintainer can push the correction to the bot's branch.

Reset the develop branch

Make a new branch from master:

git checkout master
git switch -c post-x.y.z-release-reset

Update the version number for the next development cycle:

python scripts/update_version.py -v x.y.z.dev0

The version number must comply with PEP 440.

Lint and format Python files: ruff check . and ruff format . from the project root.

Create and merge (don't squash) a pull request from this branch into develop.

Conda

To manually publish a new version to conda forge, substitute one's own fork of conda-forge/flopy-feedstock into the following steps:

  1. Download the *.tar.gz file for the just-created release from the GitHub website.

  2. Calculate the sha256 checksum for the *.tar.gz using:

    openssl sha256 flopy-version.tar.gz

    from a terminal.

  3. Pull upstream flopy-feedstock into local copy of the flopy-feedstock fork repo:

    cd /Users/jdhughes/Documents/Development/flopy-feedstock_git
git fetch upstream
git checkout master
git reset --hard upstream/master
git push origin master --force

  4. Rerender the repo using conda-smithy (make sure conda-smithy is installed using conda):

    conda smithy rerender

  5. Update the version number in {% set version = "3.2.7" %} and sha256 in the flopy-feedstock fork meta.yaml file.

  6. Commit changes and push to flopy-feedstock fork.

  7. Make pull request to flopy-feedstock