Release checklist

This is a guide on what needs to be done before a release can be made.

General steps

  • Pick someone to be a release manager

  • Pick a release date

  • Pick a RC1 (release candidate) date which should be ~1 month before the release

Prior to generating a release

  • Update the ZAMS model file by running the work directory found in data/star_data/zams_models/create_z2m2_y28. This may take up to an hour or so. This will generate the file data/star_data/zams_models/zams_z2m2_y28.data. Use the ZAMS model plotting script to verify that the HR diagram and central compositions look reasonable, and commit the new data file.

  • Update figures in the docs by running the update_docs_figures script in the star/test_suite/ folder. These figures should be checked to make sure they look reasonable. Currently not all test suite problems autogenerate figures. Pay special attention if the model numbers in the filenames of saved figures have changed (script will print an ERROR message) – this indicates some commit to MESA has slightly changed the results of these problems, and currently the README.rst file needs to be manually updated with the new image filename and the test as to be re-run (e.g. ./each_test_run -u 13). A new release should not be made if one of the figures degrade in quality.

Removing files

Any files that should not be part of the final release should be added to the .gitattributes file. This will prevent the file(s) or folders from appearing in the zip archive.

Documentation

  • The Changelog should be updated.

Note

At a minimum this should mention options that are removed/replaced and how to convert from a previous version to the newest version.

Testing

  • TestHub should report all tests pass for both Linux and macOS on multiple machines and with different OS versions.

  • The previous SDK version should be tested.

Note

If the previous SDK does not pass we can decide whether to bump the minimum SDK version or fix the issues.

  • A non-SDK machine should test the test_suite.

  • At least one Windows machine should get tested.

  • Recalibrate test suite cases (things like simplex_solar_calibration and example_astero).

Additional Testing

Additional checks that are not essential but should be done if there is time.

  • Check test_memory runs and reports no memory leaks.

  • Check MESA compiles with SHARED_LIBS=True

  • Run with FPE checking on.

Linters

There are a number of linters in the linters folder. The following MUST be run before release:

  • fix_inlists.py: This makes sure certain options are disabled in the test suite.

  • check_photos.py: This makes sure the photo read/writes are in sync and is needed to ensure photos work.

Note

If any thing was added or removed from a photo, remember to bump the version star_def_version in star_data/public/star_data_def.inc

Other linters should be run if possible.

Making a release

Run the release script in MESA_DIR. This requires $MESA_DIR to be set and takes one argument the release version (you should add the r prefix as well). For version rXX.YY.Z this script will make a branch release/rXX.YY.Z and then it:

  • Updates data/version_number

Note

data/version_number is normally not included in a commit (it must be explicitly added via git add -f. as we gitignore it).

  • Updates docs/source/conf.py

  • Updates Doxyfile

To the new version rXX.YY.Z.

This script will also make zip archive, which can be used for local testing to make sure the release builds.

Note

This zip folder is not what we release. The actual zip folder is generated by Github, so that should be tested as well once it has been made.

Note

Once the script has generated the new release branch, update the changelog headings from “Changes in main” to “Changes in rXX.YY.Z” etc, and delete the note near the top of the changelog about changes in main relative to the most recent release.

The release script does not push any changes to Github. Once you are ready to push the release branch, this must be done manually with a git push. (This is a separate step from pushing the tag in the next step.)

Release steps

To make an actual release (once testing is complete), first push the git tag made by the release script:

  • git push origin XX.YY.Z

This is the key bit, as the Github release will be anchored to this tag.

Note

The tag follows PEP440 standards – there is no r or - (hyphen) in the tag (unlike the branch name) – so readthedocs can automatically determine the stable version and add version warning banners.

Go to https://github.com/MESAHub/mesa/releases and craft a new release following the guidelines here.

Note

If this is a RC release, then make sure to click This is a pre-release.

Add an appropriate title and description. The title should be kept simple, like Release: rXX.YY.Z.

Once created, this zip folder should be downloaded and checked that it installs and runs a test case.

Zenodo

Once the zip folder has been created, it should be uploaded to Zenodo prior to sending a release announcement. This helps avoid swamping our GitHub bandwidth with user downloads.

  • For a pre-release, do not upload to the main MESA Zenodo repository. Instead upload to its own Zenodo entry. This can be done on a personal account.

  • Official releases need to be uploaded to this MESA Zenodo page.

Send an email to mesa-users

Send an email announcing the release, this should include:

  • Link to Zenodo for download (not GitHub)

  • A brief summary of the changes

  • A link to the Changelog

  • Highlight any very disruptive changes that might have occurred

  • Any new mesa-developers

  • Acknowledge those in the community who have helped in some way during this release (bug reports, PRs, testing during the RC phase, being very active on mesa-users)

  • Remind people that we welcome any contributions (big or small)

Acknowledging support

Getting all authors who committed code (this includes merged pull requests)

.. code-block:: console

git log –format=’%aN’ r21.12.1..HEAD | sort -u

Listing all commits that acknowledge help from someone

.. code-block:: console

git log –all –grep=”-by” r21.12.1..HEAD

Post release fixes

By having the release be in a separate branch, we can push changes if we need to to fix issues. However, this should be done with caution. Changes to the documentation (highlighting some workarounds are fine). Making changes to the code itself is more tricky (due to the Zenodo upload being fixed and change requiring a new Zenodo upload). It may be easier if a version needs fixes to simply push a new release, and flag the current release as not working.

New readthedocs version

First gain access to the readthedocs account (that is currently accessible by Rich, Evan, Joey, Earl, Meridith, and Philip). Then:

  • Go to the Versions page

  • Find the release tag (not the branch) and Activate it

  • We want the tag (following PEP440 standards), so readthedocs can automatically deduce the stable version and create a version banner warning.

  • Wait for it to build, and check that it works

  • Go to the Admin page and then the Advanced settings tab

  • Switch the default version to the release

  • Click save at the bottom of the page

  • To update docs post release, we will need to use git to change the tag to point to the new commit (SHA).