1.1. METplus Official Release

Create a new vX.Y.Z official release from the develop branch.

1.1.1. Open Release Issue

  • Define a new issue in the METplus repository to create the new release.

    • “Create the METplus vX.Y.Z release” for an official or bugfix release.

    • “Create the METplus vX.Y.Z-betaN (or -rcN) release” for a development release.

  • For an official or development release, assign the issue to the corresponding METplus development project.

  • For a bugfix release, assign the issue to the organization level support project.

  • Select the target milestone.

1.1.2. Clone the Project Repository

  • Create and work in a new directory to ensure a fresh environment:

mkdir release-X.Y.Z
cd release-X.Y.Z
  • Run the clone command to obtain the repository.

Using SSH:

git clone git@github.com:dtcenter/METplus

Using HTTP:

git clone https://github.com/dtcenter/METplus
  • Enter the project repository directory:

cd METplus

1.1.3. Checkout the Develop Branch

  • Checkout the develop branch:

git checkout develop

1.1.4. Create Release Feature Branch

  • Create a feature branch in which to update the version number and add release notes being sure to include the GitHub issue number for the new release.

git checkout -b feature_NNNN_vX.Y.Z       # for an official or bugfix release
git checkout -b feature_NNNN_vX.Y.Z-betaN # for a development release
git checkout -b feature_NNNN_vX.Y.Z-rcN   # for a development release

1.1.5. Update Release Date

  • The release date is stored in metplus/RELEASE_DATE in YYYYMMDD format.

  • Change the value stored in this file to match the current date.

1.1.6. Update Release Notes

You can refer to the GitHub Project board to see what has changed for this release. Open the following URL in a browser:

  • Click on the project that corresponds to this release, i.e. METplus-X.Y.Z Development

  • Navigate to the “Closed Issues” tab. If this tab does not exist, see GitHub Projects to manage development to create it.

  • Update the release-notes.rst file found in the User’s Guide directory.

  • Consider organizing release notes into logical groups (e.g. Enhancements, Bugfixes, Documentation, etc.) and modifying GitHub issue titles for consistency. The release notes should match the GitHub issue titles, when possible.

  • Use your best judgement to apply bold formatting for any major or important changes.

  • When creating the official release, combine the beta release sections into one section (i.e. “Version X.Y.Z release notes (YYYYMMDD)”).

  • Commit changes and push to GitHub.

1.1.7. Update Upgrade Instructions

Occasionally, changes will be made to software that will require users to make changes to their configuration files in order to use the latest release. For example, when ensemble post-processing was added to Gen-Ens-Prod and removed from Ensemble-Stat, users were required to make changes in their configuration files.


This section is not always applicable.

To alert the users to the necessary steps involved with the upgrade:

  • Update the Upgrade Instructions section of the release-notes.rst file found in the METplus User’s Guide directory with the necessary information.

  • Add an “upgrade instructions” link next to the appropriate METplus component (METplus) after “latest” and before “development” in the METplus Components Release Note Links section in the release-notes.rst file in the METplus User’s Guide in the METplus GitHub repository ONLY if there are Upgrade Instructions for this release.

1.1.8. Rotate Authorship

The METplus team rotates the list of authors in the citation instructions for each official release:

  • Compare the current METplus User’s Guide citation to the most recent official release.

  • If needed, update the authorship order, moving the previous first author to the end of the list. Note the format difference in the first name in the citation list compared with the others. The first name in the citation list is “Last name, First Initial.” and all of the following names as “First Initial. Last Name”. Please maintain that format as it is the most common format for citations.

  • The author list is typically found in the conf.py file in the documentation directory, i.e. docs/conf.py. Most of the component repositories store the list of authors in a variable named author_list. Please ensure that changes to this list match the correct format listed above. In the METplus repository, the conf.py file has variable named CURRENT_AUTHORS that is a list of the authors to rotate. To rotate, move the first item in the list to the end of the list. There is logic in this file to read the list and format it properly to match the expected format for citations.

  • Review the list of authors in the citation and at the top level of the documentation and update as needed.

  • Commit changes and push to GitHub

1.1.9. Update the version numbers in the manage externals files

There are a few .cfg files used by Manage Externals that should include the correct tag or branch that corresponds to the METplus Coordinated Release for each METplus component.


For a METplus X.Y.Z Coordinated Release, the version of the components are typically:

  • MET: X+6

  • METviewer: X

  • METplotpy: X-3

  • METcalcpy: X-3

  • METdataio: X-3


For the METplus 4.1.0 release:

  • MET is 10.1.0

  • METviewer is 4.1.0

  • METplotpy is 1.1.0

  • METcalcpy is 1.1.0

  • METdataio is 1.1.0

For the METplus 5.0.0 release:

  • MET is 11.0.0

  • METviewer is 5.0.0

  • METplotpy is 2.0.0

  • METcalcpy is 2.0.0

  • METdataio is 2.0.0

This may not always be the case. When in doubt, check the components’ repository or ask another developer. Update build_components/Externals_stable.cfg

Ensure the tag for each component is correct. It should match the format vX.Y.Z where X.Y.Z is the version of that component. For example, MET should be v11.0.0 for METplus 5.0.0. Update .github/parm/Externals_metdataio_stable.cfg

Ensure the branch value is correct. It should match the format main_vX.Y where X.Y is the version of that component. For example, METdataio should be main_v2.0 for METplus 5.0.0. Update .github/parm/Externals_metplotcalcpy_stable.cfg

Ensure the branch for each component is correct. It should match the format main_vX.Y where X.Y is the version of that component. For example, METplotpy and METcalcpy should be main_v2.0 for METplus 5.0.0.

1.1.10. Merge Release Issue

  • After updating the release-specific content on a release feature branch, submit a pull request to merge those changes back into the source branch.

1.1.11. Create Release Reference Branch

  • For METplus, the corresponding MET release must be created before starting this step. Specifically, a DockerHub tag on dtcenter/met that is named (X+6).Y-latest must already exist. For example, for METplus 4.1.0, the MET DockerHub tag for 10.1-latest must be built. See https://hub.docker.com/repository/docker/dtcenter/met/general for a list of existing tags.

  • Create a branch from the develop branch for the reference branch for the new official release and push it to GitHub. The branch name should match the format main_vX.Y-ref where X.Y is the major/minor release number.

cd METplus
git checkout develop
git pull
git checkout -b main_vX.Y-ref Update the version number

Update the content that should go into the release version but remain unchanged in the develop branch.

Remove -dev from the version number:

  • As of METplus 4.0.0, we are naming releases with X.Y.Z format even if Z is 0.

  • As of METplus v4.0.0, the file containing the version number is located at metplus/VERSION (in earlier releases, the file was located at docs/version or doc/version).

  • In the develop branch, the version should match the upcoming release with -dev added to the end like X.Y.Z-betaN-dev, i.e. 4.0.0-beta1-dev

  • Remove -dev from the version number so that it matches the release you are creating.

Commit these changes. Push Reference Branch to GitHub

git push -u origin main_vX.Y-ref

Pushing this branch to GitHub should trigger the GitHub Actions automation that runs all of the use cases and creates Docker data volumes with the output data. These data will be used to verify that any bugfixes applied to the main_vX.Y branch does not break any of existing logic. Monitor GitHub Actions Workflow

Navigate to https://github.com/dtcenter/METplus/actions and verify that a Testing workflow was triggered on the main_vX.Y-ref branch.

  • Wait until the entire workflow has run successfully. The final job entitled “Create Output Docker Data Volumes” should create Docker data volumes for each use case category on DockerHub (dtcenter/metplus-data-dev). The names of these volumes start with output-. Create main branch and push to GitHub

  • After the truth data volumes have been generated, create the main_vX.Y branch off of the -ref branch.

git checkout -b main_vX.Y
git push -u origin main_vX.Y

1.1.12. Push Release Branch to GitHub

Push the release branch to GitHub:


git push origin $release_branch

1.1.13. Create Release on GitHub

  • Go to Releases on GitHub and click ‘Draft a new release’

  • Set the tag based on the version, starting with ‘v’, i.e. vX.Y.Z-betaN, vX.Y.Z-rcN, or vX.Y.Z

  • Set the branch value to ‘develop’ for a development release or ‘main_vX.Y’ for a bugfix or official release

  • Choose a release name (i.e. METplus-X.Y.Z-betaN, METplus-X.Y.Z-rcN, or METplus-X.Y.Z)

  • Add a link to the release notes from the METplus User’s Guide, i.e. https://METplus.readthedocs.io/en/vX.Y.Z-betaN/Users_Guide/release-notes.html (Note: the URL will not be active until the release is created) Refer to a previous release to easily copy and modify this information.

  • Add links to the HTML and PDF versions of the METplus User’s Guide on ReadTheDocs. https://METplus.readthedocs.io/_/downloads/en/vX.Y.Z-betaN/pdf/ (Note: the URL will not be active until the release is created) Refer to a previous release to easily copy and modify this information.

  • Add link to METplus_Data and add a note to instruct users to use sub-directory corresponding to this release, i.e. v4.0) Refer to a previous release to easily copy and modify this information.

  • If this is a development release, check the box that says “This is a pre-release” and uncheck “Set as latest release”

  • Click on “Publish release”.

1.1.14. Update DTC Website

  • Navigate to https://dtcenter.org and sign in to the Drupal interface.

  • Navigate to the downloads page for the METplus repository at https://dtcenter.org/community-code/metplus/download

  • Click on the Edit button to edit the Downloads page.

  • Create a new Software Release for the newly released version by clicking on Add New Release.

    • For Full Title of Release type “METplus Version X.Y.Z”.

    • For Related Community Code select both the METplus and the METplus Wrappers options (For Macs, hold the Command key to select both).

    • For Version Label type “METplus X.Y.Z-betaN”.

    • Select the release type (Recommended for official or bugfix releases or Development for development versions).

    • Enter the release date.

    • Click on Add Code Download then click Add Link to add links for each of the following:

      • Add Link: The URL should be the release page that was just created under the GitHub Releases tab and the link text should be the name of the release (i.e. METplus X.Y.Z-betaN).

      • Add Link: Link text should be “User’s Guide” and the URL should be the top level directory of the User’s Guide hosted on the web. Beta releases can use “develop” in the URL, but for official releases, please ensure the link uses the branch name (e.g. main_vX.Y) as opposed to the tag name (e.g. vX.Y.Z). For example, use “https://metplus.readthedocs.io/en/main_vX.Y/Users_Guide/” and NOT “https://metplus.readthedocs.io/en/vX.Y.Z/Users_Guide/

      • Add Link: Link text should be “Existing Builds and Docker” and the URL should be the latest Existing Builds page, i.e. https://dtcenter.org/community-code/metplus/metplus-X-Y-existing-builds (If creating a new official release, be sure to add a new Existing Builds and Docker page, if one was not already created.)

    • Inside the text box in the “Release Notes” section provide a direct link to the release-notes.html file in the User’s Guide.

    • Click on “Create Release”.

    • Update the existing releases, as needed.

      • For a development release, ensure the “Release Type” is set to Development and change any previous Development versions to Other.

      • For a bugfix or official release, change any previous Recommended versions to Other.

      • For an official release, remove the corresponding development releases.

    • Create or edit the “Coordinated METplus Version X.Y” software release.

      • For an official release, create the “Coordinated METplus Version X.Y” release entry if it doesn’t already exist. Ensure the “Release Type” is set to Recommended. Consider changing the “Release Type” of previous coordinated releases from Recommended to Other. Add links for the METplus X.Y.Z, the METplus “Documentation”, the METplus “Existing Builds and Docker” page, and the “Release Notes”. Make the Release Notes a link to the METplus Release Notes.

      • For a bugfix release, update the existing link and text in the “Coordinated METplus Version X.Y” release section with the X.Y.Z+1 information.

    • Make any other necessary website updates. For example, adding the User’s Guide to https://dtcenter.org/community-code/metplus/documentation

    • Click on “Save”.

1.1.15. Finalize Release on GitHub

  • Update milestones:

    • Edit the milestone for the current release by updating the Due date with the actual release date.

    • Close the current milestone.

    • Create a new milestone for the first bugfix release (e.g. first vX.Y.1 (bugfix) release).

    • If necessary, create a new milestone for the next official release (e.g. next vX.Y.Z release).

  • Update issues:

    • Close the GitHub issue for creating this official release.

    • If necessary, reassign any remaining issues for the current milestone to other milestones.

  • Update projects:

  • Update branches:

    • Remove any remaining stale development branches from the new release.

    • Update the repository settings by resetting the Default branch to the new main_vX.Y branch:

-> Settings
-> Branches (tab on left)
-> change the drop down to new branch (click on stacked arrows icon next to the edit icon)
-> update branch protection rules

1.1.16. Update Version on Develop Branch

Switch to the develop branch and change metplus/VERSION value to the next release after this one with -dev added to the end. Releases will loosely following these names, but are subject to change:

Release Version

New Develop Version











1.1.17. Update the Documentation on the Web

Because Read the Docs is configured to automate the building of new “main” branches in the METplus components’ repositories, nothing needs to be done to build the documentation for the new release. See the Read the Docs section for further information. For an official release, it is important to update the “Default branch” to this latest “main” branch. An administrator of the METplus component repository will need to do the following to update the default branch:

  • Log into their Read the Docs account

  • Click on the appropriate METplus component project

  • Click on Admin in the top menu

  • Click on Advanced Settings in the left menu

  • Select the new default branch in the dropdown menu for “Default branch” (e.g. main_v4.0.0)

  • Ensure that “latest” points to the new default branch by clicking on “View Docs”in the upper right corner and confirm that the version number displayed in the header is the desired version for “latest”.

1.1.18. Update DTC Web Server Data Create Directory for Next Release

On the DTC web server where the sample input data for use cases is hosted, run the setup_next_release_data.py script for the next upcoming release to set up the data directory for the next major/minor version development. The script can be found in the METplus repository in internal/tests/use_cases. The file should be found in the home directory of the met_test user on the DTC web server host. It is linked to the file in the METplus repository. Pull the latest changes from the develop branch before running the script:

runas met_test
cd /home/met_test/METplus
git checkout develop
git pull

Now run the script passing in the version of the next release, i.e. if creating the v4.1.0 release, pass in v5.0 as the argument:

/home/met_test/setup_next_release_data.py ${new_version}

See the comments in the script for more details. Ensure that the script runs without error and that the newly created directory contains links to all of the sample data tar files:

ls -lh /home/met_test/METplus_Data/${new_version}

Untar each of the sample data tarfiles so the model_applications and met_test directories exist:

cd /home/met_test/METplus_Data/${new_version}
for f in sample_data*; do echo tar xzf $f;tar xzf $f; done

Check if the met_test and model_applications directories now exist:

ls -lh /home/met_test/METplus_Data/${new_version}

1.1.19. Update Zenodo

In the METplus GitHub repository scroll down to the README file and check the METplus Coordinated Release Digital Object Identifier (DOI) on Zenodo. Once all METplus components have been released, gather the zip files for each METplus component release in the METplus Verification System Coordinated Release and upload them to create a new version on Zenodo.

1.1.20. Set up Reminder to Delete Beta Tags

Help keep the GitHub repositories and DockerHub clean by removing beta tags. Do not delete the beta tags for this release right away. Please set a calendar reminder or schedule an email to be sent two weeks from the release date as a reminder to delete the beta tags in both GitHub and DockerHub (if applicable).