2.1. METplus Official Release
Create a new vX.Y.Z official release from the develop branch.
2.1.1. Open Release Issue
Define a new GitHub issue for creating this new release.
Instructions
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.
2.1.2. Clone the Project Repository
Clone the repository onto your local machine.
Instructions
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
2.1.3. Checkout the Main Branch
Instructions
Checkout the main branch for the X.Y release. If you are creating the METplus-X.Y.Z official or bugfix release, checkout main_vX.Y.
git checkout main_vX.Y
2.1.4. Create Release Feature Branch
Create a feature branch to update the version number and add release notes.
Instructions
Include the GitHub issue number in the feature branch 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 for Official Release
Update the version number for this official release.
Instructions
The VERSION file is located in the metplus subdirectory.
Remove the -rcN suffix so the version matches the format X.Y.0
2.1.6. Update Docker Image Workflow
Update the list of versions whose Docker images should be rebuilt on schedule.
Instructions
The Create Release Docker Images workflow is defined in ‘.github/workflows/release-docker-images.yml’.
In the ‘workflow_dispatch’ section, consider updating the default ‘release_version’ to be built.
In the ‘define-matrix’ job, update the ‘version_list’ for schedule events:
Add the new vX.Y.Z version to the list of versions.
For bugfix releases, remove the previous bugfix version, e.g. vX.Y.Z-1. Only the most recent ‘vX.Y.Z’ bugfix version for each ‘vX.Y’ release can be listed to avoid ambiguity when updating ‘X.Y-latest’ tags on Docker Hub.
For official releases, remove earlier versions only if their support has ended.
2.1.7. Update Release Date
Update the date for the official release.
Instructions
The release date is stored in metplus/RELEASE_DATE in YYYYMMDD format.
Change the value stored in this file to match the current date.
2.1.8. Update Release Notes
Update the release notes for this release.
Instructions
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. 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)”).
For the METplus repository, remove the development timeline information under the METplus Release Information section prior to creating the official release.
Commit changes and push to GitHub.
2.1.9. Update Upgrade Instructions
Update the upgrade instructions for this release.
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 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.
2.1.10. Update Development Timeline
Update the details in the development timeline.
Instructions
For the METplus repository, update the development timeline under the METplus Release Information section.
If you are creating an official release, edit the actual release date for the release and remove development timeline information for all beta/rc versions.
If you are creating a beta1 release, add development timeline information with approximate dates for planned development cycles.
For other development release, edit the actual release dates and planned release dates for future development cycles, as needed.
Commit changes and push to GitHub.
2.1.12. Update DockerHub Info in Existing Builds
Update existing build information on DockerHub.
Instructions
In docs/Users_Guide/existing_builds.rst, update the information under the DockerHub dropdown menu.
Review the version numbers for the MET, METplus, and METplus Analysis DockerHub items and update them as needed.
Update the “Last Updated:” information to include the release date, e.g. November 14, 2024.
If you are creating a beta1 release, remove the text that says “- Coming Soon!” in the dropdown menu label.
Commit changes and push to GitHub.
2.1.13. 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.14. Create Release on GitHub
Create the new release on GitHub.
Instructions
Ensure that any and all dependent releases for METplus have been created according to Release Dependencies.
Go to Releases on GitHub and click ‘Draft a new release’
For ‘Choose a tag’, create a new tag based on the version, starting with ‘v’ (i.e. vX.Y.Z-betaN, vX.Y.Z-rcN, or vX.Y.Z)
Define the ‘Target’ branch as:
‘develop’ for a beta development release
‘main_vX.Y’ for a release candidate, bugfix, or official release
Define the ‘Release title’ based on the repository name and version, without a leading ‘v’ (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”.
Click on “Publish release”.
2.1.15. Update DTC Website
METplus software releases are announced on the DTC website. Add or update information about software releases on the website.
Instructions
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. Beta releases can use “develop” in the URL, but for rcN and official releases, please ensure the link uses the branch name (e.g. main_vX.Y). For example, use https://metplus.readthedocs.io/en/main_vX.Y/Users_Guide/release-notes.html#existing-builds
In the Release Notes text box 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.
Edit the “Coordinated METplus Version X.Y” software release.
For a bugfix release, update the existing link and text in the “Coordinated METplus-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 at the bottom of the page.
2.1.16. Finalize Release on GitHub
Return to GitHub to finalize the details of this release.
Instructions
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 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 projects:
Close the existing development project for the current milestone.
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/METplus -> Settings -> Scroll down to the Default branch section -> Click the stacked arrows button next to default branch name -> Select the new default branch from the dropdown list -> Click the Update button
2.1.17. Update the Documentation on the Web
Update the default branch for Read the Docs.
Instructions
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 Settings in the top right menu
Select the new default branch in the dropdown menu for “Default branch” (e.g. main_v4.0.0) and click the Save button at the bottom of the page
Ensure that “latest” points to the new default branch by clicking on “latest” build that just started and click on “Version latest” to view the build run. When it finishes running, click on “View Docs” on the right of the page and confirm that the version number displayed in the header is the desired version for “latest”.
2.1.18. Add Next Version to Lookup Table
Add version information for the next coordinated release.
Instructions
In the develop branch, modify the metplus/component_versions.py file to add an entry for the next coordinated release.
If the X.0 release was just created, add an entry for the X.1 release.
If the X.1 release was just created, add an entry for the X+1.0 release.
Set the appropriate X.Y.0 versions for each component. Maybe sure to set the Z number to 0.
Set the version for metexpress to None (not a string).
For example, if the coordinated 6.0 release was just created, add:
'6.1': {
'metplus': '6.1.0',
'met': '12.1.0',
'metplotpy': '3.1.0',
'metcalcpy': '3.1.0',
'metdataio': '3.1.0',
'metviewer': '6.1.0',
'metexpress': None,
},
For example, if the coordinated 6.1 release was just created, add:
'7.0': {
'metplus': '7.0.0',
'met': '13.0.0',
'metplotpy': '4.0.0',
'metcalcpy': '4.0.0',
'metdataio': '4.0.0',
'metviewer': '7.0.0',
'metexpress': None,
},
2.1.19. Coordinated Release Announcement
Let the team know about this new coordinated release.
Instructions
Send an email to the ‘metplus-all’ Google group indicating the completion of the coordinated METplus release. This email serves as notification to the project manager that an announcement can now be sent to the METplus community.
2.1.20. Create a Reminder to Delete Stale Releases
Two weeks after the official release, remove stale development tags and releases.
Instructions
Help keep the GitHub repositories and DockerHub clean by removing beta/rc tags and releases created during development for this official release. Do not delete the tags/releases 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 tags/releases.
In GitHub, first delete all of the releases that contain beta or rc in the name, then delete all corresponding tags. Delete any beta/rc tags in DockerHub if applicable.