contributing: Update VERSION file using commands (#2331)

The script provides an action as sub-command and updates the VERSION file based on the input and the current state of the VERSION file and gives an error when the operation does not make sense with the given VERSION file content.

* Supports switch to release, rc, dev versions and updates of major, minor, and micro numbers.
* Can increase minor version by two with --dev for odd versions.
* Suggest commit message based on the current release procedure.
* General instructions on using the script included separately.
* Applied in the release procedure.
* Add Bash eval output for convenience in the release procedure.

doc/howto_release.md

@@ -11,21 +11,24 @@
 
 ### Update VERSION file to release version number
 
-Directly edit VERSION file in GH interface:
+Modify the VERSION file use the dedicated script, for RC1, e.g.:
 
-<https://github.com/OSGeo/grass/blob/releasebranch_8_2/include/VERSION>
+```bash
+./utils/update_version.py status
+./utils/update_version.py rc 1
+```
 
-Example:
+The script will compute the correct version string and print a message containing it into the terminal (e.g., "version: GRASS GIS 8.2.0RC1").
+
+Commit with a commit message suggested by the script, e.g.:
 
 ```bash
-8
-2
-0RC1
-2022
+git diff
+git commit -m "version: GRASS GIS 8.2.0RC1" include/VERSION
+git show
+git push upstream
 ```
 
-Commit with version message, e.g. "GRASS GIS 8.2.0RC1".
-
 ### Create release tag
 
 (For background, see <https://help.github.com/en/articles/creating-releases>)
@@ -43,22 +46,17 @@ git fetch --all --prune && git checkout releasebranch_8_2 && \
  git merge upstream/releasebranch_8_2 && git push origin releasebranch_8_2
 
 # create version env var for convenience:
-MAJOR=`cat include/VERSION | head -1 | tail -1`
-MINOR=`cat include/VERSION | head -2 | tail -1`
-RELEASE=`cat include/VERSION | head -3 | tail -1`
-VERSION=${MAJOR}.${MINOR}.${RELEASE}
-echo $VERSION
-
-# RELEASETAG variable not really needed any more:
-TODAY=`date +"%Y%m%d"`
-RELEASETAG=release_${TODAY}_grass_${MAJOR}_${MINOR}_${RELEASE}
-echo $RELEASETAG
+# Get VERSION and TAG as variables.
+eval `./update_version.py status --bash`
 ```
 
 #### Tag release (on GitHub)
 
+Version and tag are the same for all releases:
+
 ```bash
 echo "$VERSION"
+echo "$TAG"
 ```
 
 To be done in GH interface:
@@ -111,22 +109,23 @@ head ChangeLog_$VERSION
 gzip ChangeLog_$VERSION
 ```
 
-### Reset include/VERSION file to git version
-
-Directly edit VERSION file in GH interface:
+### Reset include/VERSION file to git development version
 
-<https://github.com/OSGeo/grass/blob/releasebranch_8_2/include/VERSION>
+Use a dedicated script to edit the VERSION file, for RC1, e.g.:
 
 Example:
 
 ```bash
-8
-0
-1dev
-2021
+./utils/update_version.py dev
 ```
 
-Commit as "back to dev"
+Commit with the suggested commit message and push, e.g.:
+
+```bash
+git show
+git commit include/VERSION -m "version: Back to 8.2.0dev"
+git push upstream
+```
 
 Reset local copy to GH:
 

utils/update_version.md

@@ -0,0 +1,99 @@
+# Updating Version File
+
+Version file (`include/VERSION`) can be updated using the _update_version.md_ script.
+
+The script captures the logic of updating the version file incorporating
+the common actions and workflow checks.
+
+## Usage
+
+Use `--help` to get the information about actions available as sub-commands:
+
+```sh
+./utils/update_version.py --help
+```
+
+Some sub-commands have short documentation on their own:
+
+```sh
+./utils/update_version.py minor --help
+```
+
+All commands return YAML output on success and return non-zero return code on failure.
+
+## Examples
+
+### Checking Current Status
+
+The _status_ command prints content of the version file as YAML
+and adds today's date and constructs a version string:
+
+```sh
+./utils/update_version.py status
+```
+
+Example output:
+
+```yaml
+today: 2022-04-27
+year: 2022
+major: 3
+minor: 2
+micro: 0dev
+version: 3.2.0dev
+```
+
+Naturally, this also checks that the version if is accessible and fails otherwise.
+
+The _status_ command prints input for Bash _eval_ with `--bash`:
+
+```bash
+eval `./utils/update_version.py status --bash`
+echo $VERSION
+```
+
+### Updating Minor Version
+
+Let's say we are at development-only version 3.1.dev and just created
+a new branch for 3.2 release, so we want to update the minor version
+to the next minor version:
+
+```sh
+./utils/update_version.py minor
+```
+
+Separately, or as part of other changes, now is the time to commit,
+so the script suggests a commit message:
+
+```yaml
+message: Use the provided title as a commit message
+title: 'version: Start 3.2.0dev'
+```
+
+### Error Handling
+
+The commands detect invalid states and report error messages.
+Continuing in the previous example, an attempt to increase
+the micro version will fail:
+
+```sh
+./utils/update_version.py micro
+```
+
+The error message explains the reason, a micro version should be increased
+only after the release:
+
+```text
+Already dev with micro '0dev'. Release first before update.
+```
+
+### Updating Development-only Version
+
+Development-only versions have odd minor version numbers and are never actually
+released. Given the branching model, all these versions are on the _main_ branch,
+so there the minor version is increased by two. This can be done by running
+the _minor_ command twice or by using the `minor --dev`:
+
+```sh
+./utils/update_version.py minor --dev
+```