Skip to content

Release Process

Jump to bottom
Zach Burnett edited this page Jul 19, 2023 · 28 revisions

1. Update metadata in the main / master branch

These steps should be undertaken on the main / master branch:

  1. Edit the change log CHANGES.rst; in the entry corresponding to your intended release (a.b.c (unreleased)), change unreleased to the current date in YYYY-MM-DD format. Also add a new change log entry above, with the format a.b.d (unreleased).

  2. Commit your changes and push to main / master on spacetelescope/stdatamodels.

2. Manage the release branch

If you're making a major or minor version release, then the release branch will not yet exist. If you're releasing a patch version, then a release branch will already exist. Select one of the next two sections accordingly. The following steps assume that the spacetelescope/stdatamodels remote is named upstream.

New major / minor version

  1. Fetch and checkout the upstream master:
git fetch --all --tags
git checkout upstream/master
  1. Inspect the log to ensure that no commits have snuck in since your changelog updates:
git log
  1. Create a new release branch. The name of the release branch should share the major and minor version of your release version, but the patch version should be x. For example, when releasing 1.8.0, name the branch 1.8.x.
git checkout -b a.b.x
  1. Push the branch to the upstream remote:
git push -u upstream HEAD
  1. GitHub actions should notice the new branch and run the tests. Wait until the job completes before proceeding.

Patch release of an existing major / minor version

In the case of a patch release, the release branch will already exist.

  1. Checkout and freshen release branch (this assumes that your local branch is already tracking upstream/a.b.x):
git checkout a.b.x
git pull
  1. Cherry-pick relevant commits from master that should be included in the patch release (including the new changelog commit):
git cherry-pick ...
  1. Push updates to the upstream remote:
git push upstream HEAD

3. Review the release branch's latest CI run

The creation or update of the release branch should have triggered a CI job on GitHub actions. Find the latest build on the a.b.x branch in the Actions tab:

https://github.com/spacetelescope/stdatamodels/actions/workflows/ci.yml

4. Run tests on downstream packages

Once the release branch is situated, it's a good idea to confirm that our release candidate doesn't break the following test suites:

  • jwst regression tests (add a PEP508 string to the pip dependencies input field that points to the release commit, e.g. git+https://github.com/spacetelescope/stdatamodels.git@fbd97cc)

5. Tag the most recent commit with the release version

At this point, you should have the release branch checked out and ready to tag.

  1. Create an annotated tag with a name that matches your intended release:
git tag -a a.b.c -m "Tagging a.b.c release on a.b.x release branch"
  1. Push the new tag to the upstream remote:
git push upstream a.b.c

6. Maintain the stable branch (if necessary)

The stable branch points to the latest official release of stdatamodels. If the current release has become the latest, then the next step is to rewrite the stable branch to point our new tag.

git checkout stable
git reset --hard a.b.c
git push upstream stable --force

7. Publish the package to PyPI

Publish to GitHub releases

  1. Visit the spacetelescope/stdatamodels repository's releases page. You should see the new tag for your release version listed at the top, without a link or description.

  2. Click Draft a new release.

  3. Select the existing tag, and title the release the same as the tag (i.e., a.b.c).

  4. Press the Publish release button.

Confirm PyPI publish

The repo is configured with an automated workflow that should publish the package to PyPI when the release is published. After this workflow completes, you can confirm that you're able to install the new version using pip:

pip install stdatamodels==a.b.c

Clone this wiki locally