Release Checklist

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.

Prepare changes for release

Goal: Make local updates to the invest repository for the release

To be executed by the Release Manager when we decide to do the release.

• Create an issue for this release on natcap/invest
• On your fork:
  • Create a branch for the release.
    • For a minor release:
      • Pull the latest changes from release/<version> upstream.
      • create a new branch based off of release/<version> for these changes
    • For a bugfix release:
      • Create a new branch (release/<version>) off of main
• Commit changes needed for the release
  • Edit HISTORY.rst for release
    • Update the version string
    • Add today's date
  • Update Makefile so that the UG, sample data, and test data revisions are correct for the minor release
  • Verify API docs for correctness (make apidocs)
  • Verify requirements are correct in python setup.py --long-description (generated from README_PYTHON.rst release artifacts
• Push your new branch to your fork to trigger builds.
• Verify the InVEST JSON download link handler naming conventions match the generated InVEST

Wait for builds to complete

On push, github actions will run tests and build artifacts. If needed, re-run actions jobs and/or make changes to the release. Artifacts are pushed to GCS and also saved to GH Actions.

Proceed when:

• All binary artifacts created without error
• Binary artifacts uploaded to GCS without error

Test the release binaries

Goal: Verify (by hand) the release builds work as expected.

To be executed by the Release Manager when binaries for the above changes have been built.

• Test this
• Have one other engineer test the release as well

Test the Workbench

On a Windows computer:

• Download the workbench
• Install the build and all sample data
• Try running a few models and interacting with anything that changed in this release

On a Mac (James and Emily are happy to help!):

• Download the workbench
• Install the build and all sample data
• Try running a few models and interacting with anything that changed in this release

PR changes into release/<version>

When changes on the Release Manager's branch are ready for release (everything's there except for the tag), submit a PR into release/<version> and have it reviewed by another engineer.

Continue to make any changes if necessary.

Publish the release

Goal: Make the release available to the world

To be executed by the Release Manager when binaries are ready for release.

• Create a release object on the target github repo

  • Use notes in HISTORY.rst for this release, converted to markdown
  Script for pandoc/sed conversion

  # Requires Pandoc, sed
  $ ./ci/release/build-release-text-from-history.sh <version>

  • Use the release/<version> branch as the target.

When the release object is created, release/<version> will be tagged and the tag will be pushed. Binaries will be created and uploaded to GCS in response.

When binaries finish uploading:

• Download release artifacts from GCS:
  • InVEST sample data (complete archive)
  • InVEST Workbench - Windows
  • InVEST Workbench - Mac
  • InVEST User's Guide archive
  • natcap.invest binary distributions
  • natcap.invest source distribution
• Attach the release artifacts to the release objects
• Use twine to upload python distributions to PyPI:

  # Example for regular (interactive username and password)
  $ twine upload ./natcap.invest*
  
  # Example for uploading with an API key (required if you have 2FA)
  $ twine upload --username=__token__ --password="$PYPI_API_TOKEN" ./natcap.invest-*
  

NOTE: As of 2023-02-30, the website's cron executes daily at about 4:30am PT. Remember to factor this in to the timing of announcements.

Release cleanup

Goal: Tidy up the repository after the release.

• PR the release/<version> branch into main
• Delete the release/<version> release branch
• Create a new branch for the next minor release if needed
• Scrub any unresolved issues included in 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.

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 natcappers@lists.stanford.edu
• 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!

😎