Release Process

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. Update the documentation changelog (docs/changes.rst) to add a What's New in ASDF a.b.c? section for this release. Use the following template:

What's New in ASDF a.b.c?
=========================

The ASDF Standard is at vx.y.z.

Changes include:

* First change
 
* ...

Filling in the appropriate versions and changes of note from the project changelog.

3. Update the asdf-standard pointer, if necessary. This should have already been done at the time that the last asdf-standard PR was merged, but it's easy to forget.

4. 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. The following steps assume that the spacetelescope/asdf remote is named upstream.

Major or minor version release

1. Fetch and checkout the upstream master:

$ git fetch upstream
$ git checkout upstream/master

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.

$ git checkout -b a.b.x

4. Push the branch to the upstream remote:

$ git push -u upstream HEAD

5. Travis should notice the new branch and run the tests. Wait until the build passes before proceeding.

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

2. Cherry-pick relevant commits from master that should be included in the patch release (including the new changelog commit):

$ git cherry-pick ...

3. Push updates to the upstream remote:

$ git push upstream HEAD

Travis should notice the updated branch and run the tests. Wait until the build passes 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 the following test suites:

• astropy
• jwst unit tests
• jwst regression tests
• specutils
• gwcs

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"

2. Push the new tag to the upstream remote:

$ git push upstream a.b.c

Maintain the stable branch (if necessary)

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

Tag master for further development (if necessary)

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.

$ 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 PyPI, GitHub, astroconda, and conda-forge.

Publish to PyPI

Before proceeding, you will need to install twine.

1. Checkout the tag to be released and ensure that the asdf-standard submodule is updated:

$ git checkout a.b.c
$ git submodule update

2. Clean the directory to remove build artifacts and other such cruft:

$ git clean -fxd

3. Create the package:

$ python setup.py sdist --format=gztar

4. Upload the package to PyPI's test server:

$ twine upload --repository-url https://test.pypi.org/legacy/ dist/*

5. Visit the ASDF project page on the test server and confirm that the new version uploaded successfully. There may be errors due to the package description failing to render.

6. Create a fresh environment and confirm that the package installs from test.pypi.org:

$ pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ asdf[tests]==a.b.c

7. Confirm that tests pass on the installed package:

$ python -c "import asdf; asdf.test()"

8. Upload the package to the main PyPI server:

$ twine upload dist/*

9. Visit the ASDF project page and confirm that the new version uploaded successfully.

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 new What's New in ASDF a.b.c section (excluding the title) from the docs to the description field. Change any formatting from reStructuredText to markdown.

5. Press the Publish release button.

Publish to astroconda

1. Open a PR against the astroconda-contrib repository with the following updates to the asdf metadata file:

• Update the version variable near the top of the file to match your new tag/version.

• Compare the build and run requirements to asdf's setup.py, updating dependency versions and adding or removing dependencies as needed.

2. Following merge and the nightly build process, confirm that your new version of ASDF is available from the astroconda channel.

Publish to conda-forge

If your new version doesn't require any dependency changes, then you can skip step 1 -- the regro-cf-autotick-bot bot will automatically create a PR with updated version and hash_value variables.

1. Open a PR against the asdf-feedstock repository with the following updates to the asdf metadata file:

• Update the version variable near the top of the file to match your new tag/version.

• Update the hash_value variable to match the SHA-256 hash of your new version's PyPI distribution archive (available from the PyPI Download files page).

• Compare the build and run requirements to asdf's setup.py, updating dependency versions and adding or removing dependencies as needed.

• Review the about section for changes.

2. Following merge and the nightly build process, confirm that your new version of ASDF is available from the conda-forge channel.

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.