feat: bin/annotate.sh and document usage

bin/annotate-tag.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+# Annotate a tag from Github
+# FAQ: Github releases create annotated (not lightweight) tags
+# SEE: https://github.com/orgs/community/discussions/4924
+
+# Whether string is a valid SemVer version
+is_valid_semver() {
+  local version=$1
+  # SemVer regex pattern (simplified for illustration)
+  local semver_pattern="^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$"
+  [[ $version =~ $semver_pattern ]]
+}
+
+# Is argument (string) provided?
+if [ $# -ne 1 ]; then
+  echo "Usage: $0 <version_string>"
+  exit 1
+fi
+
+# Capture arguments
+version_string=$1
+
+# Is string a valid SemVer version?
+if ! is_valid_semver "$version_string"; then
+  echo "Error: Invalid SemVer format. Please provide a valid version string like '3.11.6' or 'v3.12.0-beta.3' or 'v3.6.0-8-gd1dbcab'."
+  exit 1
+fi
+
+# Annotate the tag
+git pull
+git checkout "$version_string"
+git tag -d "$version_string"
+git tag -a "$version_string" -m "chore: $version_string"
+
+# Report success
+echo "Annotated tag \"$version_string\"."

docs/contributing.md

@@ -43,15 +43,14 @@ Only appointed team members may release versions.
 1. Create new branch for version bump.
 1. Update `CHANGELOG.md`.
 1. Update version via:\
-   `npm version N.N.N`
+  `npm version N.N.N`
 1. Commit, push, PR, review, merge.
 1. Create release and tag on GitHub.
-1. Replace Github's unannotated tag with an annotated one:
-   - `git pull`
-   - `git checkout vN.N.N`
-   - `git tag -d vN.N.N`
-   - `git tag -a vN.N.N -m "chore: vN.N.N"`
-   - `git push --tags --force`
+1. Annotate Github's tag:\
+  `bin/annotate-tag.sh vN.N.N`\
+  (where `N.N.N` is the version tag)
+1. Overwrite remote tag with annotated one:\
+  `git push --tags --force`
 
 <!-- Link Aliases -->