2.1. MET Official Release
Create a new vX.Y.Z official release from the develop branch.
2.1.1. Open Release Issue
Define a new issue in the MET repository to create the new release.
“Create the MET vX.Y.Z release” for an official or bugfix release.
“Create the MET vX.Y.Z-betaN (or -rcN) release” for a development release.
For an official or development release, assign the issue to the corresponding MET development project.
For a bugfix release, assign the issue to the organization level support project.
Select the target milestone.
2.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/MET
Using HTTP:
git clone https://github.com/dtcenter/MET
Enter the project repository directory:
cd MET
2.1.3. Checkout the Develop Branch
Checkout the develop branch:
git checkout develop
2.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
2.1.5. Update Version Number
Update the version in the code and documentation:
If necessary, update the met_version variable in src/basic/vx_util/util_constants.h which defines the version number written to the MET output files.
In docs/conf.py, update the version, release_year, and release_date variables for the documentation.
If necessary, update the version number listed in the MET configuration files:
Default configuration files in data/config.
Sample configuration files in scripts/config.
Test configuration files, searching recursively, in internal/test_unit/config.
If necessary, add a new data/table_files/met_header_columns_VX.Y.txt defining the columns names for this version.
If necessary, add a new internal/test_unit/hdr/met_X_Y.hdr file defining the column names for this version for the test scripts.
2.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:
https://github.com/orgs/dtcenter/projects
Click on the project that corresponds to this release, i.e. MET-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.
2.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.
Note
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 MET User’s Guide directory with the necessary information.
Add an “upgrade instructions” link next to the appropriate METplus component (MET) 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.
2.1.9. 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.
2.1.10. Update DTC Web Server Data
2.1.10.1. Create Directory for This Release
On the DTC web server where the sample input data for unit tests is hosted, create a new directory for this official major/minor release.
The GitHub Actions automation creates version-specific input test data volumes. It pulls input test data from the DTC web server, creates a Docker data volume, and pushes the result to the dtcenter/met-data-dev DockerHub repository.
Log on to the DTC web server and run:
runas met_test
cd ${MET_TEST_INPUT}
cp -r develop vX.Y
Confirm the result at https://dtcenter.ucar.edu/dfiles/code/METplus/MET/MET_unit_test.
2.1.11. Create Release Reference Branch
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 MET git checkout develop git pull git checkout -b main_vX.Y-ref
2.1.11.1. 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.
2.1.11.2. Monitor GitHub Actions Workflow
Navigate to https://github.com/dtcenter/MET/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/met-dev).
2.1.12. Create Release Branch
Create a branch from the develop branch for the new official release and push it to GitHub.
cd MET git checkout develop git pull git checkout -b main_vX.Y git push -u origin main_vX.Y
2.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. MET-X.Y.Z-betaN, MET-X.Y.Z-rcN, or MET-X.Y.Z)
Add a link to the release notes from the MET User’s Guide, i.e. https://MET.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 MET User’s Guide on ReadTheDocs. https://MET.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.
If this is a development release, check the box that says “This is a pre-release”
Click on “Publish release”.
2.1.14. Update DTC Website
Navigate to https://dtcenter.org and sign in to the Drupal interface.
Navigate to the downloads page for the MET 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 “MET Version X.Y.Z”.
For Related Community Code select both the METplus and the MET options (For Macs, hold the Command key to select both).
For Version Label type “MET 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: Link text should be the file name of the tar file and the URL should be the .tar.gz file created in the “Attach Release Tarfile” step.
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 MET 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 MET 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, the flowchart at https://dtcenter.org/community-code/model-evaluation-tools-met/system-architecture.
Click on “Save”.
2.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:
Close the existing development project for the current milestone.
If necessary, see GitHub Projects to manage support to create a support project for the current METplus coordinated release.
If necessary, see GitHub Projects to manage development to create a development project for the next milestone.
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:
https://github.com/dtcenter/MET -> 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
2.1.16. 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”.
2.1.17. Update Zenodo
In the MET GitHub repository scroll down to the README file and check the MET Digital Object Identifier (DOI) on Zenodo. Use the zip file for the new MET release to create a new version on Zenodo.