3.1. METdatadb Official Release
Create a new vX.Y.Z official release from the develop branch.
3.1.1. Open Release Issue
Define a new issue in the METdatadb repository to create the new release.
“Create the METdatadb vX.Y.Z release” for an official or bugfix release.
“Create the METdatadb vX.Y.Z-betaN (or -rcN) release” for a development release.
For an official or development release, assign the issue to the current METdatadb development project.
For a bugfix release, assign the issue to the organization level support project.
Select the target milestone.
3.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/METdatadb
Using HTTP:
git clone https://github.com/dtcenter/METdatadb
Enter the project repository directory:
cd METdatadb
3.1.3. Checkout the Develop Branch
Checkout the develop branch:
git checkout develop
3.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
3.1.5. Update Version Number for Release
Remove -dev from the version number:
We are naming releases with X.Y.Z format even if Z is 0.
The file containing the version number is located at docs/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.
In docs/conf.py, update the version, release_year, and release_date variables for the documentation.
3.1.6. Update Release Notes
You can refer to the GitHub Issues page to see what has changed for this release. Open the following URL in a browser:
https://github.com/dtcenter/METdatadb/issues
Click on the Projects tab and select the project (under Repository) that corresponds to the release you are creating.
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.
3.1.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.1.9. Create Release Branch
Create a branch from the develop branch for the new official release and push it to GitHub.
cd METdatadb git checkout develop git pull git checkout -b main_vX.Y git push -u origin main_vX.Y
3.1.10. Push Release Branch to GitHub
Push the release branch to GitHub:
release_branch=main_vX.Y
git push origin $release_branch
3.1.11. 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. METdatadb-X.Y.Z-betaN, METdatadb-X.Y.Z-rcN, or METdatadb-X.Y.Z)
Add a link to the release notes from the METdatadb User’s Guide, i.e. https://METdatadb.readthedocs.io/en/vX.Y.Z-betaN/Users_Guide/release-notes.html (Note: the URL will not be active until the release is created)
Add a link to the PDF of the METdatadb User’s Guide, if available. The PDF can be downloaded from ReadTheDocs if it is available, i.e. https://METdatadb.readthedocs.io/_/downloads/en/vX.Y.Z-betaN/pdf/ (Note: the URL will not be active until the release is created)
If this is a development release, check the box that says “This is a pre-release”
Click on “Publish release”.
3.1.12. Update DTC Website
Navigate to the downloads page for the METdatadb repository at https://dtcenter.org/community-code/metplus/download
Sign in to the Drupal interface and 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 “METdatadb Version X.Y.Z”.
For Related Community Code select both the METplus and the METdatadb options (For Macs, hold the Command key to select both).
For Version Label type “METdatadb 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, 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, 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.
Make any other necessary website updates.
Click on “Save”.
3.1.13. Finalize Release on GitHub
Close the GitHub issue for creating this official release.
Edit the milestone for the current release by updating the Due date with the actual release date.
If necessary, create a new milestone for the next official release (e.g. next vX.Y.Z release).
If necessary, reassign any remaining issues for the current milestone to the next one.
Close the current milestone.
Confirm that all existing development projects for the current milestone are closed.
If necessary, create development projects for the next milestone (e.g. METdatadb-X.Y.Z-beta1, beta2, beta3).
Update the repository settings by resetting the Default branch to the new main_vX.Y branch:
https://github.com/dtcenter/METdatadb -> Settings -> Branches (tab on left) -> change the drop down to new branch
3.1.14. Update Version on Develop Branch
Change METdatadb/docs/version value to the next release after this one with -dev added to the end. Releases will loosely follow these names, but are subject to change:
Release Version |
New Develop Version |
---|---|
X.Y.Z-beta1 |
X.Y.Z-beta2-dev |
X.Y.Z-beta2 |
X.Y.Z-beta3-dev |
X.Y.Z-beta3 |
X.Y.Z-rc1-dev |
X.Y.Z-rc1 |
X.Y.Z-dev |
X.Y.Z |
(X+1).0.0-beta1-dev |
3.1.15. 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”.