Skip to content

Release Checklist

Jump to bottom
James Douglass edited this page Dec 19, 2024 · 15 revisions

Release Checklist

This checklist is meant to ensure that we accomplish the required steps when doing a bugfix or minor release. It is not meant to make decisions for us.

Pre-Release: Should a release happen?

Goal: Determine whether a release should happen at this time.

Consider these questions as a group to come to a decision.

  • For a bugfix release:
    • Are there unreleased changes on main?
    • Is there a critical bugfix to distribute to users?
    • Are tests passing on main?
    • Are there any bugfix PRs that are about to be merged that should be included in the release?
    • Is there already an outstanding, unfinished bugfix release?
  • For a minor release:
    • Are all issues on the release milestone resolved?
    • Are there any issues on the release milestone that no longer make sense?
    • Have the latest changes from main been merged into this release branch?
    • Are there any known outstanding issues (tracked or untracked)?
    • Are there any outstanding PRs against release/<version>?

Pre-Release: Notify interested folks

If a release is being planned:

  • Send a slack message to #natcapsoftwaremodelin with the latest build and ask for feedback. Tag Stacie, Jesse and others who we know to be interested in the release, such as the scientists who had a hand in developing a new model.
  • Slack Elana to let her know what the rough timeline for the InVEST release will be.

Before initializing release automation

  • Create an issue for this release on natcap/invest
  • Make sure the sample data, and test data revisions in the Makefile are correct
  • Make sure the User's Guide revisions in the Makefile are correct. Often this should be the HEAD of main, but sometimes a release branch exists in the User's Guide. Make sure to merge the UG main into that release branch, then set the Makefile revision as the HEAD of the release branch
  • Verify API docs for correctness (make apidocs)
  • Verify requirements are correct in pyproject.toml
  • (Minor releases only) PR the release branch into main

Initialize the release automation

On the natcap/invest repository, go to the "Actions" tab, and in the left-hand sidebar, click "Release (Part 1 of 2). Then, on the right-hand-side, you should see a dropdown that says "Run workflow". Click that, select the branch to base this release off of (usually main) and enter the version number (e.v. 3.14.2). Click the green "Run workflow" button.

If Part 1 fails on git checkout, check the AUTORELEASE_BOT_PAT token, it may have expired.

This will create a new autorelease branch, make a few changes for the release and open a PR for it into main.

Take a look at the PR for instructions.

See more details on the automated release process

Sign Windows Binaries

Once the release automation is complete and has uploaded binaries to everywhere they need to go, we need to sign the Windows binaries. This is unfortunately a manual process and must be done by someone in possession of an appropriate code-signing certificate.

  1. Set up your yubikey by ensuring your PUK is not set to the default and that you have the Yubikey smart card minidriver installed. See the yubico docs for complete steps.
  2. On a Windows computer, download the Windows installer for the Workbench from the release page on GitHub.
  3. Open a command prompt (recommended: use "Developer Command Prompt for VS 2019") and navigate to the directory where the downloaded installer is located.
  4. Follow the steps on the yubico docs under "Procedure" to sign the installer. If you're using a Developer Command Prompt, signtool.exe will already be on your PATH.
  5. Upload the signed installer to the release page on GitHub and to Google Cloud, overwriting the binaries that are already there.

Conda-forge builds

The natcap.invest package has a conda-forge package:

When the conda-forge project detects that there is a new source distribution on PyPI, it will automatically create a new PR for the new release in the feedstock. If the package builds on all target OSes and tests pass, the feedstock is configured to automatically merge the PR, which will officially release the new version. It will generally take a few hours for the conda-forge automation to detect a new package.

As a part of the PR for a new version, conda-forge will try to import all of the files in the natcap.invest package. If this fails, it is likely that there was a new dependency added to natcap.invest that needs to be added to recipe/meta.yaml in the feedstock repo. Follow the instructions in the PR body and peruse the conda-forge maintainer docs for more information.

Release cleanup

Goal: Tidy up the repository after the release.

  • Delete the autorelease/<version> release branch
  • Scrub any unresolved issues or milestones from the release
  • If other repos (User Guide, sample-data, test-data) had release/<version> branches, this is a good time to merge them into main/master.

Communicate any changes needed

Goal: Inform people of the new release if it makes sense to do so.

Website download links must be updated manually. To do this, contact someone with edit permissions to the website, currently Elana, Terry, Doug and James.

Consider the following common items, and use your best judgement about whether it makes sense to communicate changes to each channel. Bugfix releases may not need as much fanfare as a minor release.

  • Emailing [email protected]
  • Updating the Communications Team (Elana) with any big changes so she can update website content and comms materials as needed.
  • Announce the release on #softwareteam on our slack workspace
  • Tweet the release, mention @natcapproject
  • Post to the forums

Celebrate!

Do something fun!

😎

Clone this wiki locally