How to make a Gammapy release

This page contains step-by-step instructions how to make a Gammapy release. We mostly follow the Astropy release instructions and just lists the additional required steps.

Feature Freeze and Branching

1. Follow the Astropy feature freeze and branching instructions. Instead of updating the whatsnew/<version>.rst update the docs/release-notes/<version>.rst.

2. Update the entry for the feature freeze in the Gammapy release calendar.

Releasing the first major release candidate

A few days before the planned release candidate:

1. Fill the changelog docs/release-notes/<version>.rst for the version you are about to release.

2. Update the author list manually in the CITATION.cff.

3. Open a PR including both changes and mark it with the backport-v<version>.x label. Gather feedback from the Gammapy user and dev community and finally merge and backport to the v<version>.x branch.

On the day of the release candidate:

1. In the gammapy-webpage repo:

   • Add an entry for the release candidate like v1.0rc1 or v1.1rc1 in the download/index.json file, by copying the entry for dev tag. As we do not handle release candidates nor bug fix releases for data, this still allows to fix bugs in the data during the release candidate testing.

   • In the download/install folder, copy a previous environment file file as gammapy-1.0rc1-environment.yml.

   • Adapt the dependency conda env name and versions as required in this file.

2. Update the CITATION.cff date and version by running the dev/prepare-release.py script.

3. Locally create a new release candidate tag on the v1.0.x, like v1.0rc1 for Gammapy and push. For details see the Astropy release candidate instructions.

4. Once the tag is pushed the docs build and upload to PyPi should be triggered automatically.

5. Once the docs build has succeeded find the tutorials_jupyter.zip file for the release candidate in the gammapy-docs repo and adapt the download/index.json to point to it.

6. Update the entry for the release candidate in the Gammapy release calendar.

7. Create a testing page like Gammapy v1.0rc testing.

8. Advertise the release candidate and motivate developers and users to report test fails and bugs and list them on the page created before.

Releasing the final version of the major release

1. Create a new release tag in the gammapy-data repo, like v1.0 or v1.1.

2. Update the datasets entry in the download/index.json file in the gammapy-webpage repo to point to this new release tag.

3. Locally create a new release tag like v1.0 for Gammapy and push. For details see the Astropy release candidate instructions, but leave out the rc1 suffix.

4. In the gammapy-docs repo:

   • Wait for the triggered docs build to finish.

   • Edit stable/switcher.json to add the new version.

5. In the gammapy-webpage repo:

   • Mention the release on the front page and on the news page.

   • In the download/install folder, copy a previous environment file file as gammapy-1.0-environment.yml.

   • Adapt the dependency conda env name and versions as required in this file.

   • Adapt the entry in the download/index.json file to point ot the correct environment file.

   • Find the tutorials_jupyter.zip file for the new release in the gammapy-docs repo and adapt the download/index.json to point to it.

6. Update the entry for the actual release in the Gammapy release calendar.

7. Finally:

   • Update the Gammapy conda-forge package at conda-forge/gammapy-feedstock

   • Encourage the Gammapy developers to try out the new stable version (update and run tests) via the GitHub issue for the release and wait a day or two for feedback.

Post release

Steps for the day to announce the release:

1. Send release announcement to the Gammapy mailing list and on Gammapy Slack.

2. If it’s a big release with important new features or fixes, also send the release announcement to the following mailing lists (decide on a case by case basis, if it’s relevant to the group of people):

   • https://groups.google.com/forum/#!forum/astropy-dev

   • CTAO AS WG list (cta-wg-as@cta-observatory.org)

   • hess-forum list (hess-forum@lsw.uni-heidelberg.de)

3. Make sure the release milestone and issue is closed on GitHub

4. Update these release notes with any useful infos / steps that you learned while making the release (ideally try to script / automate the task or check, e.g. as a make release-check-xyz target).

5. Update version number in Binder Dockerfile in gammapy-webpage repo master branch and tag the release for Binder.

6. Open a milestone and issue for the next release (and possibly also a milestone for the release after, so that low-priority issues can already be moved there) Find a release manager for the next release, assign the release issue to her / him, and ideally put a tentative date (to help developers plan their time for the coming weeks and months).

7. Start working on the next release.

Make a Bugfix release

1. Add an entry for the bug-fix release like v1.0.1 or v1.1.2 in the download/index.json file in the gammapy-webpage repo. The datasets entry should point to last stable version, like v1.0 or v1.1. We do not provide bug-fix release for data.

2. Follow the Astropy bug fix release instructions.

3. Follow the instructions for a major release for the updates of CITATION.cff, the modifications in the gammapy-docs and gammapy-webpage repos as well as the conda builds.