diff --git a/doc/howto_release.md b/doc/howto_release.md index 38ae8f4a018..a88f1a1baa3 100644 --- a/doc/howto_release.md +++ b/doc/howto_release.md @@ -22,7 +22,8 @@ Update your remotes and switch to branch: git fetch --all --prune && git checkout releasebranch_8_2 ``` -Confirm that you are on the right branch and have no local changes: +Confirm that you are on the right branch and have no local changes +and that you have no local unpushed commits: ```bash # Should show no changes: @@ -30,6 +31,7 @@ git status # Should give no output at all: git diff git diff --staged +# Should give no output: git log upstream/releasebranch_8_2..HEAD # Should give the same as last commits visible on GitHub: git log --max-count=5 @@ -42,16 +44,23 @@ and optionally update your own fork: git merge upstream/releasebranch_8_2 && git push origin releasebranch_8_2 ``` -Use `git log` and `git show` to verify the result: +Verify the result: ```bash +# Should give no output: +git log upstream/releasebranch_8_2..HEAD +# Should give the same as last commits visible on GitHub: git log --max-count=5 -git show ``` -Any time later, you can use `git log` and `git show` to see the latest +Now or any time later, you can use `git log` and `git show` to see the latest commits and the last commit including the changes. +```bash +git log --max-count=5 +git show +``` + ## Update VERSION file to release version number Modify the VERSION file use the dedicated script, for RC1, e.g.: @@ -67,8 +76,18 @@ Commit with a commit message suggested by the script, e.g.: ```bash git diff -git commit -m "version: GRASS GIS 8.2.0RC1" include/VERSION +git commit include/VERSION -m "version: GRASS GIS 8.2.0RC1" +``` + +Check that there is exactly one commit on your local branch and that it is the version change: + +```bash +git status git show + +Push the tag to the upstream repo: + +```bash git push upstream ``` @@ -105,20 +124,36 @@ Check on GitHub or use GitHub CLI: gh run list --branch releasebranch_8_2 ``` +Some time was needed to run the checks, so before getting back to creating the tag, +confirm that you are on the right branch which is up to date: + +```bash +git status +git log --max-count=5 +``` + Create an annotated tag (a lightweight tag is okay too, but there is more metadata -stored for annotated tags including a date): +stored for annotated tags including a date; message is suggested by the version script): ```bash git tag $TAG -a -m "GRASS GIS 8.2.0RC1" ``` +List all tags (annotated will be at the top of both lists): + +```bash +git tag -n --sort=-creatordate +git tag -n --sort=-taggerdate +``` + Now push the tag upstream - this will trigger the automated workflows linked to tags: ```bash git push upstream $TAG ``` -If the job fails, open an issue and see what you can do manually. +If any of the tag-related jobs fails, open an issue and see what you can do manually +so that you can continue in the release process. ### Create release notes @@ -130,9 +165,9 @@ so change the current directory: cd utils ``` -For major and minor releases, GitHub API gives good results -because it contains contributor handles and can identify new contributors, -so use with the _api_ backend, e.g.: +For major and minor releases, GitHub API gives good results for the first +release candidate because it contains contributor handles and can identify +new contributors, so use with the _api_ backend, e.g.: ```bash python ./generate_release_notes.py api releasebranch_8_2 8.0.0 $VERSION @@ -146,15 +181,31 @@ The _git log_ command operates on commits, so use use the _log_ backend: python ./generate_release_notes.py log releasebranch_8_2 8.2.0 $VERSION ``` +In between RCs and between last RC and final release, the _log_ backend is useful +for showing updates since the last RC: + +```bash +python ./generate_release_notes.py log releasebranch_8_2 8.2.0RC1 $VERSION +``` + +For the final release, the changes accumulated since the first RC need to be +added manually to the result from the _api_ backend. + The script sorts them into categories defined in _utils/release.yml_. However, these notes need to be manually edited to collapse related items into one. Additionally, a _Highlights_ section needs to be added with manually identified new major features for major and minor releases. For all releases, a _Major_ section may need to be added showing critical fixes or breaking changes if there are any. +Change directory back to the root directory of the repo: + +```bash +cd .. +``` + ### Modify the release draft -After the automated job completes, a new release draft will be available in the GitHub +After the automated release job completes, a new release draft will be available in the GitHub web interface. You can copy-paste the created release notes to GitHub and further modify as needed. Older release description may or may not be a good inspiration: @@ -190,7 +241,7 @@ After an RC, switch to development version: ./utils/update_version.py dev ``` -After a (final) release, switch to development version for the next micro, minor, or major +After a final release, switch to development version for the next micro, minor, or major version, e.g., for micro version, use: ```bash @@ -261,12 +312,12 @@ vim wingrass-maintenance-scripts/cronjob.sh # major/minor release only Add the new version to repos which build or test addons: -- https://github.com/OSGeo/grass-addons/blob/grass8/.github/workflows/ci.yml (currently new branches only) -- https://github.com/landam/wingrass-maintenance-scripts/blob/master/grass_addons.sh (add new release related line) +- https://github.com/OSGeo/grass-addons/blob/grass8/.github/workflows/ci.yml (currently, for new branches only) +- https://github.com/landam/wingrass-maintenance-scripts/blob/master/grass_addons.sh (add new release related line for new branches and final releases) ## Close milestone -For a (final) release (not release candidate), close the related milestone at +For a final release (not release candidate), close the related milestone at . If there are any open issues or PRs, move them to another milestone in the milestone view (all can be moved at once). @@ -278,6 +329,15 @@ When the above is done and the release notes are ready, publish the release at Release is done. +## Improve release description + +For final releases only, go to Zenodo a get a Markdown badge for the release +which Zenodo creates with a DOI for the published released. + +For all releases, click the Binder badge to get Binder to build. Use it to test it and +to cache the built image. Add more links to (or badges for) more notebooks if there +are any which show well specific features added or updated in the release. + ## Create entries for the new release ### Trac Wiki release page diff --git a/utils/update_version.py b/utils/update_version.py index db07c861a39..a4d3d59b8cc 100755 --- a/utils/update_version.py +++ b/utils/update_version.py @@ -46,16 +46,24 @@ def construct_version(version_info): return f"{version_info.major}.{version_info.minor}.{version_info.micro}" -def suggest_commit_from_version_file(action): +def suggest_commit_from_version_file(action, tag): """Using information in the version file, suggest a commit message""" version_file = read_version_file() - suggest_commit(action, construct_version(version_file)) + suggest_commit(action, construct_version(version_file), tag=tag) -def suggest_commit(action, version): +def suggest_commit(action, version, tag): """Suggest a commit message for action and version""" - print("message: Use the provided title as a commit message") - print(f"title: 'version: {action} {version}'") + print("read:") + if tag: + print(" user_message: Use the provided messages for the commit and the tag.") + print(" note: Once all checks pass, you are expected to create a tag.") + else: + print(" user_message: Use the provided message for the commit") + print("use:") + print(f" commit_message: 'version: {action} {version}'") + if tag: + print(f" tag_message: 'GRASS GIS {version}'") def release_candidate(args): @@ -78,7 +86,7 @@ def release_candidate(args): micro=micro, year=this_year(), ) - suggest_commit_from_version_file("GRASS GIS") + suggest_commit_from_version_file("GRASS GIS", tag=True) def release(_unused): @@ -98,7 +106,7 @@ def release(_unused): micro=micro, year=this_year(), ) - suggest_commit_from_version_file("GRASS GIS") + suggest_commit_from_version_file("GRASS GIS", tag=True) def update_micro(_unused): @@ -127,7 +135,7 @@ def update_micro(_unused): micro=micro, year=this_year(), ) - suggest_commit_from_version_file("Start") + suggest_commit_from_version_file("Start", tag=False) def update_minor(args): @@ -156,7 +164,7 @@ def update_minor(args): write_version_file( major=version_file.major, minor=minor, micro=micro, year=this_year() ) - suggest_commit_from_version_file("Start") + suggest_commit_from_version_file("Start", tag=False) def update_major(_unused): @@ -171,7 +179,7 @@ def update_major(_unused): minor = 0 major = int(version_file.major) + 1 write_version_file(major=major, minor=minor, micro=micro, year=this_year()) - suggest_commit_from_version_file("Start") + suggest_commit_from_version_file("Start", tag=False) def back_to_dev(_unused): @@ -199,7 +207,7 @@ def back_to_dev(_unused): micro=micro, year=this_year(), ) - suggest_commit_from_version_file(action) + suggest_commit_from_version_file(action, tag=False) def status_as_yaml(version_info, today, version, tag):