3.3. MET Development Release

Create a new vX.Y.Z-betaN or vX.Y.Z-rcN development release from the develop branch while working toward an official vX.Y.Z release.

3.3.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.

3.3.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

3.3.3. Checkout the Source Branch

• If creating a beta (betaN) or first release candidate (rc1) release, checkout the develop branch:

git checkout develop

OR

• If creating a later release candidate (rc2+) release, checkout the appropriate main branch:

git checkout main_vX.Y

3.3.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

3.3.5. Update Version Number

Note

The software version number should have been updated for the next official release during development toward the first development release (e.g. beta1). If not, follow the official release instructions to do so prior to creating the first development release.

• If the official release version has already been updated (e.g. beta2+ and rc1+), do the following:

  • In ‘docs/conf.py’, update the ‘version’, ‘release_year’, and ‘release_date’ variables for the documentation.

3.3.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.

• If you are creating a beta1 release, remove the previous version’s release notes, i.e. for 3.0.0-beta1, remove all 2.Y.Z notes and start a 3.0.0 section with the format “Version X.Y.Z release notes (YYYYMMDD)”.

• If you are creating a betaX release, add a new betaX section above the betaX-1 release.

• Commit changes and push to GitHub.

3.3.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.

3.3.8. 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.

3.3.9. Create Release Reference Branch

Note

These instructions only apply when creating the first release candidate (rc1) development release. Skip this section for earlier beta (betaN) or later release candidate (rc2+) development releases.

• 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

3.3.9.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.

3.3.9.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).

3.3.10. Create Release Branch

Note

These instructions only apply when creating the first release candidate (rc1) development release. Skip this section for earlier beta (betaN) or later release candidate (rc2+) development releases.

• Create a new ‘main_vX.Y’ branch from the develop branch for the upcoming official release and push it to GitHub. All remaining development for the upcoming official release occurs on this new ‘main_vX.Y’ branch.

cd MET
git checkout develop
git pull
git checkout -b main_vX.Y
git push -u origin main_vX.Y

3.3.11. Create Release on GitHub

• Ensure that any and all dependent releases for MET 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. 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”.

3.3.12. 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 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 name of the release and the URL should be the release page that was just created under the GitHub Releases tab.

    • 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, the flowchart at https://dtcenter.org/community-code/model-evaluation-tools-met/system-architecture.

  • Click on Save at the bottom of the page.

3.3.13. Finalize Release on GitHub

Return to GitHub to finalize the details of this release.

Instructions

• Close the GitHub issue for creating this development release.

• Review the development cycles and adjust their begin and end dates, as needed.

  • From the GitHub development project, click in the top-right corner to locate and edit the “Settings”.

  • From the list of “Custom fields”, select “Cycle”.

  • Shift the next “Active” development cycle forward to begin the day after the current release, if applicable.

  • Find the recently “Completed” development cycle for the current release and modify the end date to match the actual date of the current release, if applicable.

• If necessary, reassign any remaining issues for the current development cycle to the next one.

3.3.14. Release Acceptance Testing

A single Release Acceptance Testing discussion in the METplus repository summarizes the external testing for all development cycles of the METplus components included in a coordinated release.

Instructions

• If creating a release for the first development cycle (e.g. beta1 release), check to see if the Release Acceptance Testing discussion for the next coordinated release has already been created.

• If not, create a new one to summarize external testing for all development cycles of the METplus components.

  • Locate the Release Acceptance Testing discussion for the last coordinated release.

  • Copy and paste its contents into a new discussion, being sure to update the title of the discussion and empty the contents of repository testing tables for each of the METplus components.

  • Carefully review the contents and links and update them as needed.

  • If needed, create a new label for the next METplus X.Y Coordinated Release in the METplus repository and add that label to this discussion.

• Update the contents of the Release Acceptance Testing discussion for each MET development release.

  • Locate the MET repository testing table within the body of the discussion.

  • For issues for which no external testing is required:

    • Create a single table entry for this development cycle.

    • Set the “Status” column to PASS.

    • Set the “MET Issue” column to a list of links for all of the issues.

    • Set the “Dev Cycle” column to the current development cycle name (e.g. beta1, beta2, beta3, rc1).

    • Leave the “Tester” column empty.

    • Set the “Acceptance Testing Comment Link” column to No external testing required.

  • For issues that do require external testing:

    • Create a separate table entry for each issue.

    • Set the “Status” column to OPEN.

    • Set the “MET Issue” column to link to the issue.

    • Set the “Dev Cycle” column to the current development cycle name (e.g. beta1, beta2, beta3, rc1).

    • Set the “Tester” column to a list of GitHub user name(s) to solicit their feedback.

    • Leave the “Acceptance Testing Comment Link” column empty.

  • Save your edits to the discussion.

• External testers are instructed to add comments to the discussion to summarize the status of their testing. The METplus team monitors those comments and, as needed, updates the “Status” and “Acceptance Testing Comment Link” columns of the repository testing table for each METplus component.