Bugfix Release Checklist

Bugfix Release Checklist

This checklist is meant to ensure that we accomplish the required steps when doing a 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.

• 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?

Pre-release

• Create an issue for this release on natcap/invest
• Make sure that the UG, sample data, and test data revisions in the Makefile are correct
• Verify API docs for correctness (make apidocs)
• Verify requirements are correct in pyproject.toml
• (Minor releases only) PR the release branch into main

Run the automated release process

Note The release process is intended to be atomic. Once the release process is initiated on a particular commit, it should either run to completion on that commit, or roll back to the pre-release state. No one should make changes in the autorelease branch, it is to be used by the release automation bot only. If any last-minute issues are discovered during the release process, stop, roll back, fix the issue through our routine development process, and then restart the release over from the beginning.

Release process flow chart

• Initiate the release by manually triggering the "Release (Part 1 of 2)" Github Action:

  • Navigate to the Actions tab
  • Select "Release (Part 1 of 2)" in the sidebar
  • Click the "Run workflow" dropdown
  • Leave the "Use workflow from" dropdown set to the main branch
  • In the version box, enter the version to be released
  • Click "Run workflow"
  • Wait for the workflow to succeed. If the workflow fails for any reason, it will automatically roll back. Fix any problems and then re-initiate the release.

• Navigate to the release PR created by the release workflow. This is the final checkpoint for human review of the release. Follow the instructions in the PR comment:

  • Make sure that the automated changes look correct
  • Wait for BOTH the PR checks AND the tag checks to complete
  • Test the workbench. The release should be tested by at least 2 people and on both Mac and Windows:
    • Download the workbench
    • Install the build and all sample data
    • Try running a few models and interacting with anything that changed in this release.

  If there is a bug, decline the PR. Follow the usual bugfix process (create an issue, submit a fix in a separate PR into main, request review). Once the fix has been merged, restart the release process from the beginning. If either workflow fails due to an intermittent problem, rerun it through the GitHub UI. Proceed to approve and merge the PR once it succeeds.

• When everything looks good, approve and merge the release PR. This will trigger the "Release (Part 2 of 2)" Github Action, which publishes the release on Github and PyPI.

• Verify that the PyPI release and Github release look correct. The PyPI release should contain:

  • One wheel for each combination of supported python version and operating system
  • One sdist tar archive

  The Github release should contain the above, plus:

  • InVEST sample data zip archive
  • InVEST User's Guide zip archive
  • InVEST Workbench - Windows
  • InVEST Workbench - Mac
  • Source code zip archive (automatically added by Github)
  • Source code tar archive (automatically added by Github)

Post-release

• Verify the InVEST JSON download link handler naming conventions match the generated InVEST
• 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.
• Create a new branch for the next minor release if needed

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.

• Emailing natcap-staff@lists.stanford.edu
• Updating the Communications Team with any big changes so they can update website content and comms materials as needed.
• Announce the release on #general of our Slack workspace
• Tweet the release, mention @natcapproject
• Post to the forums

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.

Updating InVEST download links on the NatCap website on demand

TODO: finish this. Waiting on https://github.com/natcap/invest/issues/49

1. Log in to the NatCap website, authenticating with your SUNetID:

2. Browse to https://naturalcapitalproject.stanford.edu/invest-software-tool-release-links-import-node-14056

3. Edit the page:

4. Go to the "Import" tab:

5. Click the "Import" button:

6. If everything imports successfully, you should see a big green status box with interesting information like this: