8.1. METexpress Official Release
Create a new vX.Y.Z official release from the develop branch.
8.1.1. Clone the Project Repository
Clone the repositories 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.
For someone at GSL doing this, it’s easiest to just do everything with METexpress as a subrepo of MATS.
Using SSH:
git clone --recurse-submodules --remote-submodules git@github.com:NOAA-GSL/MATS (requires git 2.23 or later)
Using HTTP:
git clone --recurse-submodules --remote-submodules https://github.com/NOAA-GSL/MATS (requires git 2.23 or later)
Enter the project repository directory:
cd MATS
8.1.2. Checkout the Development Branch
Checkout the development branch of the METexpress repositories.
Instructions
git checkout development
git pull
cd MATScommon
git checkout development
git pull
cd ../METexpress
git checkout development
git pull
cd MATScommon
git checkout development
git pull
cd ../..
8.1.4. Update Release Notes
Update the release notes for this release.
Instructions
You can refer to the GitHub Issues page to see what has changed for this release. Open the following URLs in a browser:
https://github.com/NOAA-GSL/MATS/issues https://github.com/dtcenter/METexpress/issues
Compile a list of all changes since the last time the development branch was merged into the main branch.
Update the top entry in MATS/MATScommon/meteor_packages/mats-common/public/MATSReleaseNotes.html to reflect these changes, as well as the new version number. Set the Production Build Date to the current date.
Update the version and release date in docs/conf.py.
Commit changes and push to GitHub origin/development.
8.1.5. Checkout the Main Branch
Checkout the main branch of the METexpress repositories.
Instructions
git checkout main
git pull
cd MATScommon
git checkout main
git pull
cd ../METexpress
git checkout main
git pull
cd MATScommon
git checkout main
git pull
cd ../..
8.1.6. Merge Development Changes to Main Branch
Merge changes into the main branch.
Note
ONLY PROCEED TO THIS STEP IF ALL OF THE AUTOMATED TESTS PASS FOR THE LATEST NIGHTLY DEVELOPMENT BUILD AT mats-docker-dev.gsd.esrl.noaa.gov (VPN required).
Instructions
Merge the latest development code into the main branch and push to origin.
git merge development
git push
cd MATScommon
git merge development
git push
cd ../METexpress
git merge development
git push
cd MATScommon
git pull
cd ../..
8.1.7. Tag App Version and Build
Tag the mains branches.
Instructions
METexpress apps are versioned as major.minor.patch. To trigger the build of a specific version, you will need to tag the current main branch in all the repositories with the version number.
git tag vX.Y.Z
git push origin vX.Y.Z
cd MATScommon
git tag vX.Y.Z
git push origin vX.Y.Z
cd ../METexpress
git tag vX.Y.Z
git push origin vX.Y.Z
cd MATScommon
git pull
cd ../..
This will cause github to automatically build the versioned app containers for the release.
8.1.8. Deploy Beta Apps
Install the built apps.
Instructions
After the apps build, which usually takes about 20 minutes, they should be installed on the dedicated beta server (mats-docker-int) for third party testing.
On mats-docker-int.gsd.esrl.noaa.gov (the beta server, VPN and permissions required), go to the container_deployment directory.
ssh www-data@mats-docker-int.gsd.esrl.noaa.gov
cd container_deployment
Add any new apps to docker_compose.yml and web/applist.json. Update the container version numbers in docker_compose.yml, and any settings files in settings/
vi docker_compose.yml
vi web/applist.json
vi settings/appname/settings.json
Redeploy the apps.
bin/redeploy production
Contact your dedicated beta tester to ensure the apps work as expected.
8.1.9. Deploy Production Apps
Deploy the METexpress apps to the production server.
Instructions
If the beta tester approves the apps, deploy them to the production server (mats-docker).
On mats-docker.gsd.esrl.noaa.gov (the production server, VPN and permissions required), go to the container_deployment directory.
ssh www-data@mats-docker.gsd.esrl.noaa.gov
cd container_deployment
Add any new apps to docker_compose.yml and web/applist.json. Update the container version numbers in docker_compose.yml, and any settings files in settings/
vi docker_compose.yml
vi web/applist.json
vi settings/appname/settings.json
Redeploy the apps.
bin/redeploy production
8.1.10. Pull Changes, Create Release Branch, And Merge To Development
Pull changes, create release branch, and merge to development.
Instructions
On your system, pull any build-related code changes.
git pull
cd MATScommon
git pull
cd ../METexpress
git pull
cd MATScommon
git pull
cd ../..
Create a release branch of the format main_vX.Y.Z. using your release version.
git checkout -b main_vX.Y.Z
git push -u origin main_vX.Y.Z
cd MATScommon
git checkout -b main_vX.Y.Z
git push -u origin main_vX.Y.Z
cd ../METexpress
git checkout -b main_vX.Y.Z
git push -u origin main_vX.Y.Z
cd MATScommon
git checkout -b main_vX.Y.Z
git push -u origin main_vX.Y.Z
cd ../..
Checkout development and merge any build-related changes.
git checkout development
git merge main
git push
cd MATScommon
git checkout development
git merge main
git push
cd ../METexpress
git checkout development
git merge main
git push
cd MATScommon
git pull
cd ../..
Add the following code to the top of MATS/MATScommon/meteor_packages/mats-common/public/MATSReleaseNotes.html.
<div>
<hr style="display: block; height: 2px; margin: 1em 0; border-top: 2px solid #000000;"/>
</div>
<div>
<p><h4>Production build date: <x-cr>Current revision</x-cr></h4>
<p><h4>Integration build date: <x-bd>Not yet built</x-bd></h4>
<p style="margin: 25px 0;"></p>
<p><h4>PUT APP VERSIONS HERE</h4>
<p style="margin: 25px 0;"></p>
<p>Changes: </p>
<p>* PUT CHANGES HERE</p>
</div>
Commit and push to origin/development.
8.1.11. 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”.
8.1.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 METexpress 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 “METexpress Version X.Y.Z”.
For Related Community Code select both the “METplus” and the “METexpress” options (For Macs, hold the Command key to select both).
For Version Label type “METexpress 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, adding the User’s Guide to https://dtcenter.org/community-code/metexpress/documentation
Click on Save at the bottom of the page.
8.1.13. Update Version Lookup Table
Modify the version lookup table in the METplus repository to include the correct version.
Instructions
Clone the METplus repository.
Using SSH:
git clone git@github.com:dtcenter/METplus
Using HTTP:
git clone https://github.com/dtcenter/METplus
Enter the METplus repository directory:
cd METplus
Checkout the develop branch
git checkout develop
Create a branch off of develop to update. Include the name of the repository and version in the name.
git checkout -b update_version_vX.Y.Z_repo
Open metplus/component_versions.py and increment the version for the appropriate METexpress entry.
Commit change, push to GitHub, and create a pull request to merge change into the develop branch.
8.1.14. Announce Release
Let users know about this new release.
Instructions
Add a link for the latest production containers on https://dtcenter.org/community-code/metexpress/download.
Select both METplus and METexpress in the multi-selector box.
Set the current release to “recommended” and reassign the previous one to “other”.
8.1.15. 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.