Skip to content

Release Process

Jump to bottom Edit New page
Brett Graham edited this page Mar 7, 2023 · 54 revisions

WARNING

This document is quite out of date and no longer reflects the release process since introduction of a LTS branch and meeseeks automation. This document needs updating to reflect the new process.

The steps below differ slightly for a major/minor release and patch release. The following steps assume that the asdf-format/asdf remote is named upstream.

Prepare master for release

These steps should be undertaken on the master branch:

  1. Update the project changelog (CHANGES.rst in the repo root) and change "unreleased" next to your intended release to the current date in YYYY-MM-DD format.

  2. Open a PR and merge the above changes to master.

Create/update 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.

Major or minor version release

  1. Fetch and checkout the upstream master:
$ git fetch upstream
$ 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 (note the trailing .x).
$ git checkout -b a.b.x
  1. Push the branch to the upstream remote:
$ git push -u upstream HEAD

Patch release

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). When cherry-picking select the merge commits (this will require you to select the parent commit -m to preserve the history):
$ git cherry-pick ...
  1. Push updates to the upstream remote (push directly to asdf-format here named upstream):
$ git push upstream HEAD

Create the release tag

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

Review CI results on the new tag

The creation of the tag should have triggered both the CI and s390x workflows. Find the results here:

https://github.com/asdf-format/asdf/actions

Tests should pass before proceeding.

Run tests on our consuming packages

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

For a patch release, tag master for further development

If we're not already working on a later release in master, then we'll need to tag the HEAD of master with a development tag. This allows the setuptools-scm plugin to identify code installed from master as the latest version. For example if version 1.1.1 was released, add a 1.1.2.dev tag.

$ git fetch upstream
$ git checkout upstream/master
$ git tag -a a.b.d.dev -m "Tagging a.b.d.dev on master"
$ git push upstream a.b.d.dev

Publish to package indexes

We publish the asdf package on GitHub, PyPI and conda-forge.

Publish to GitHub releases

  1. Visit the ASDF 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. Copy the contents of your newest CHANGES.rst entries to the description field. Change any formatting from reStructuredText to markdown.

  5. Press the Publish release button.

Publish to PyPI

This is performed automatically by the Publish to PyPI action, which will be triggered by any new GitHub release. Simply, watch for a successful result here:

https://github.com/asdf-format/asdf/actions

Publish to conda-forge

  1. Wait or the regro-cf-autotick-bot user to open a PR against the asdf-feedstock repository. This is triggered by the appearance of the new package version on pypi and can take some time (i.e., check back tomorrow).

  2. Make any necessary updates to the bot's branch and merge it.

Confirm successful readthedocs build

New tags on the repository should provoke a readthedocs build that automatically activates and builds the new version, and sets those new docs as the default. Confirm that the asdf readthedocs home shows your new What's New in ASDF a.b.c? section.

Notify the mailing lists

Send a triumphant email to asdf-developers@googlegroups.com and asdf-users@googlegroups.com to announce the new release.

Maintain the stable branch (after no issues have been found for some time)

The stable branch points to the latest official release of asdf. 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
Add a custom footer

Clone this wiki locally