This is a guide to what needs to be done before a release can be made.
- 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
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).
r12345 this script will make a branch
release/r12345 and then it:
data/version_number is normally not included in a commit (it must be explicitly added via
git add -f. as we gitignore it).
To the new version
this script will also make zip archive which can be used for local testing to make sure the release builds.
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.
The release script does not push any changes to Github. That must be done manually with a git push.
Any files that should not be part of the final release should be added to the
This will prevent the file(s) or folders from appearing in the zip archive.
- The Changelog should be updated.
At a minimum this should mention options that are removed/replaced and how to convert from a previous version to the newest version.
- A release notes document should be written.
- The release branch or tag should be added to the list of active versions on ReadTheDocs.
- 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.
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 checks that are not essential but should be done if there is time.
- Check test_memory runs and reports no memory leaks.
- Run with FPE checking on.
There are a number of linters in the
linters folder. The following MUST be run before release:
- check_photos.py This makes sure the photo read/writes are in sync and is needed to ensure photos work.
If any thing was added or removed from a photo remember to bump the version
- fix_inlists.py This makes sure certain options are disabled in the test suite.
Other linters should be run if possible.
To make an actual release (once testing is complete), first push the git tag made by the release script:
- git push origin release/r12345
This is the key bit, as the Github release will be anchored to this tag.
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
Once created this zip folder should be downloaded and checked that it installs and runs a test case.
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 dowload (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, PR’s, testing during the RC phase, being very active on mesa-users)
- Remind people that we welcome any contributions (big or small)
Getting all authors who committed code (this includes merged pull requests)
git log --format='%aN' r21.12.1..HEAD | sort -u
Listing all commits that acknowledge help from someone
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 workaround 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 and Rob). Then:
- Goto the
- Find the release branch (not the tag) and
- We want the branch not the tag so that we can update the docs post release.
- Wait for it to build and check it works
Adminpage and then the
- Switch the default version to the release.
saveat the bottom of the page