Making an MPAS release (Integrators only)

These instructions are for the steps integrators need to perform to make an MPAS release.

MPAS has two kinds of releases:

• major releases (e.g. v6.0)
• minor releases (e.g. v6.1)

Historically it is customary to give all cores 4 weeks notice for a major release and 1 week notice for a minor release. All cores should agree on a release schedule.

Hints regarding steps below:

• Instructions assume a remote to the https://github.com/MPAS-Dev/MPAS-Model repo called MPAS-Dev/MPAS-Model.
• Look at past examples to see conventions for commit message title and text.

Creating a release branch

1. Make the release branch from the correct place.
   • For a major release, the release branch should be branched off of develop. Ensure develop contains the state of the code intended for release. Merge CORE/develop branches to develop as needed and push develop to MPAS-Dev/MPAS-Model.
   • For a minor release, the release branch should be made off of the most recent tag in the major release cycle to which it belongs (e.g., v6.0, v6.1, v6.2, etc.). Bug fixes or required features should be branched off of the parent major release tag (or something older) and merged directly into the release branch. Those branches can also be merged into develop if they are needed immediately.
2. Create a release branch locally, e.g.: git checkout -b release-v6.0 MPAS-Dev/MPAS-Model/develop
   • For a major release, this should be named like release-v6.0.
   • For a minor release, this should be named like hotfix-v6.1.
3. Update the MPAS version number in Registry.xml in each core. There is a script in the MPAS-Tools repo that does this automatically, but at present it does not work correctly. However, it is easy enough to do by hand. An easy way to find all the files that need to be changed is git grep version=. Ignore results defining the XML defintion like <?xml version="1.0"?>; only worry about results like <registry model="mpas" core="atmosphere" core_abbrev="atm" version="6.0">. Edit each Registry.xml file so that the version is updated to the release version. Also update the version number in the README.md file in the root directory. Commit these changes as the first commit on the release branch.
4. Push release branch to MPAS-Dev/MPAS-Model.
5. Wait the agreed upon time for all core maintainers to perform testing and any needed minor cleanup on the release branch. For a major release this will be a few weeks, but for a minor release it can be shorter.
6. During this period, core maintainers can merge pull requests to the release branch with minor fixes/updates.

Creating the release

Once the allotted wait time is complete, the release can be finalized.

1. Locally merge the release branch into master (fetch to ensure your local repo is up to date!).
   • git checkout master
   • git reset --hard MPAS-Dev/MPAS-Model/master
   • git merge MPAS-Dev/MPAS-Model/release-v6.0
2. Tag the release on master as an annotated tag.

• git tag -a v6.0
• The tag annotation should be formatted like MPAS Version 6.0. Optionally, you can add release notes to the annotation. Try git tag -n99 to see existing examples.

3. Carefully inspect git log to make sure the history is as expected. (TODO: Add examples)
4. Push master and the release tag to MPAS-Dev/MPAS-Model.
   • git push MPAS-Dev/MPAS-Model master v6.0
5. Delete release branch
   • git push MPAS-Dev/MPAS-Model :release-v6.0
6. Merge master into develop
   • git checkout develop
   • git reset --hard MPAS-Dev/MPAS-Model/develop
   • git merge MPAS-Dev/MPAS-Model/master
   • git push MPAS-Dev/MPAS-Model develop
7. Draft and save the release description at: https://github.com/MPAS-Dev/MPAS-Model/releases
8. Update the version number in the https://mpas-dev.github.io/ page