contributing: Create tag message, add more details (#2396)

* Tag message is created automatically.
* Version script clarifies meaning of the different messages it produces.
* Commit command for changed version file is easier to edit.
* More details in the tagging and general Git procedure.
* Acknowledge that checks may take some time to run.
* Add more about tags, changes, clarify releases versus branches.
* Add Zenodo DOI step, mention Binder and notebooks.

Based on releasing 8.2.0RC2.

doc/howto_release.md

@@ -22,14 +22,16 @@ 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:
 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
 <https://github.com/OSGeo/grass/milestones>.
 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

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):