Release Process

The following steps assume that the asdf-format/asdf remote is named upstream.

Determine the type of Release

In order for our backport system and related CI to function properly. We follow a strict release policy of which branches include which releases.

• All major/minor releases must occur on their own release branches. These be named a.b.x, where a is the major version and b is the minor the minor version.
• All bugfix releases will occur directly on their release branch. That is the a.b.c will be made on the existing a.b.x branch.

In some cases the release branch may have already been created, even when no official release has been made on that version. This usually occurs when development is occurring on two distinct versions (usually ahead of a major release). As such we will divide the release process into two categories:

1. Releases requiring a release branch to be created.
2. Releases on existing branches.

Check Pull Requests

Before starting the main release process, we need to make sure that all PRs (and backports) destined for the given release have been merged.

Confirm docs on main

Readthedocs builds slightly differently for branch and PR builds. Confirm that the latest docs build on main (or the release branch) passed. https://readthedocs.org/projects/asdf/builds/

Prepare main for release

The steps should be undertaken on the main branch:

1. Update the project changelog using towncrier:

   towncrier build

2. Open a PR and containing those changes. Once the CI has passed and all branch protections have been resolved, merge the PR.

Create a release branch

If a release branch already exists for the version of ASDF being released (i.e. you are releasing a.b.c and a.b.x already exits), then skip this section and move to the next section. Otherwise, you will need to create a release branch.

1. Fetch and checkout the upstream main:

$ git fetch upstream
$ git checkout upstream/main

2. Inspect the log to ensure that no commits have snuck in since your changelog updates:

$ git log

3. 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

4. Push the branch to the upstream remote:

$ git push -u upstream HEAD

Create the release tag

At this point, the release branch for your release should exist and have all the desired changes in it assuming you followed earlier. Now we can create the release tag:

1. Checkout the release branch:

$ git checkout a.b.x

2. 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"

3. 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 the CI and Downstream workflows. Find the results here, and ensure all the relevant CI is passing before proceeding. In particular, pay close attention to any unexplained warnings or failures in the Downstream workflow, as this will indicate if the release will break something in one of our main downstream packages.

Run Regression Tests

Once the release branch is situated, it's a good idea to confirm that our release candidate doesn't break other packages' regression tests. In particular, it is important to check the regression tests for:

• jwst
• romancal

Publish Release

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. Then confirm that it appears on PyPi

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. This will be required if the release included changes to ASDF's dependencies.

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.

Tag main

This step must be done AFTER the release is published (after the publish action runs) to avoid the likely situation for a new release where the head of main has the same commit as the new release branch. Tagging main prior to the release publish action running will create a development tag with the same commit hash as the new release tag and the action will incorrectly publish as a development release.

If we're not already working on a later release in main, then we'll need to tag the HEAD of main with a development tag. This allows the setuptools-scm to identify code installed from main 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/main
$ git tag -a a.b.d.dev -m "Tagging a.b.d.dev on main"
$ git push upstream a.b.d.dev