Adding versioning workflow [bump] (#8)

* [info] Update info.yaml version to 2.5.0

* adding versioning workflow

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: gwct

.githooks/README.md

@@ -0,0 +1,121 @@
+# CONTRIBUTING.md
+
+## Introduction
+
+Thank you for contributing to this project.
+
+This repository uses Git hooks and structured commit messages to manage versioning metadata in `lib/info.yaml`. When making commits, your messages help automate version bumps and update commit metadata. Please follow the guidelines below.
+
+---
+
+## Setup (one-time)
+
+This project uses project-scoped Git hooks stored in `.githooks/`.
+
+To enable them in your local clone:
+
+1. Set Git to use the project hooks directory:
+
+   ```bash
+   git config core.hooksPath .githooks
+   ```
+
+2. Make sure all scripts are executable:
+
+   ```bash
+   chmod +x .githooks/*
+   ```
+
+---
+
+## Commit Message Tags
+
+Your commit message controls how the version is updated. Tag your commits with one of:
+
+| Tag                | Action                                 | Example                                |
+|--------------------|----------------------------------------|----------------------------------------|
+| `[major]`          | Bump major version (X → X+1.0.0)       | `Rewrite internals [major]`            |
+| `[minor]`          | Bump minor version (Y → Y+1)           | `Add option for format [minor]`        |
+| `[patch]`          | Bump patch version (Z → Z+1)           | `Fix typos and style [patch]`          |
+| `[bump]`           | Same as `[patch]`, for convenience     | `Update citation link [bump]`          |
+| `[vX.Y.Z]`         | Set exact version (overrides bumps)    | `Release new version [v2.5.0]`         |
+| No tag or `[no v]` | Skip versioning; update timestamp only | `Adjust spacing [no v]`                |
+
+Multiple tags are allowed, but the most significant one will take effect:
+`[major] > [minor] > [patch]/[bump]`
+
+Redundant tags will trigger a warning.
+
+---
+
+## What Happens Automatically
+
+When you commit:
+
+- The `commit-msg` hook:
+  - Parses your message
+  - Validates version changes
+  - Updates `lib/info.yaml` fields:
+    - `version`
+    - `releasedate-*`
+    - `latest-commit-msg`
+    - `latest-commit-date`
+  - Rejects duplicate or downgraded versions
+  - Prints warnings for large version jumps
+
+- The `post-commit` hook:
+  - If `info.yaml` was modified, creates a second commit:
+
+    ```
+    [info]
+    ```
+
+  - This ensures metadata is added reliably without interfering with your working commit
+
+---
+
+## Examples
+
+```bash
+git commit -m "Add option [minor]"
+git commit -m "Adjust wording [bump]"
+git commit -m "Release 3.0 final [v3.0.0]"
+git commit -m "Improve formatting"
+```
+
+After each commit, you can check that the hooks ran and updated the info file with:
+
+```bash
+git log --oneline -n 2
+git diff HEAD~1 lib/info.yaml
+```
+
+---
+
+## Notes
+
+- Be sure to `git add` the files you want in the commit before running `git commit`
+- You do not need to stage or edit `lib/info.yaml` — it is handled automatically
+- Do not squash or remove `[info]` commits — they are part of the versioning log
+
+---
+
+## Troubleshooting
+
+- **Hook not firing?**
+  - Check that `.githooks/commit-msg` and `.githooks/post-commit` are executable
+  - Ensure `git config core.hooksPath` is set properly
+
+- **Version not updating?**
+  - Make sure you included a bump tag in your commit (like `[patch]` or `[v2.3.0]`)
+
+- **Accidentally repeated a version?**
+  - Add `[allow same version]` to override
+
+---
+
+## Thank You
+
+We appreciate your contributions. Reliable versioning ensures reproducibility and clear project history.
+
+Need help? Open an issue or contact the maintainers directly.

.githooks/commit-msg renamed to .githooks/commit-msg.disabled

@@ -0,0 +1,144 @@
+#!/bin/bash
+set -e
+
+YAML_FILE="lib/info.yaml"
+COMMIT_MSG="$(git log -1 --pretty=%B)"
+DATE=$(date +'%Y-%m-%d')
+
+if [ ! -f "$YAML_FILE" ]; then
+    echo "YAML file not found: $YAML_FILE"
+    exit 0
+fi
+
+# [info] auto-commit check
+if [ "$COMMIT_MSG" == "[info]" ]; then
+    exit 0
+fi
+
+ESCAPED_COMMIT_MSG=$(printf '%s' "$COMMIT_MSG" | sed 's/"/\\"/g')
+
+# Update latest-commit-msg
+if grep -q "^latest-commit-msg:" "$YAML_FILE"; then
+    sed -i "s/^latest-commit-msg:.*/latest-commit-msg: \"$ESCAPED_COMMIT_MSG\"/" "$YAML_FILE"
+else
+    echo "latest-commit-msg: \"$ESCAPED_COMMIT_MSG\"" >> "$YAML_FILE"
+fi
+
+# [no v] — only update latest-commit-date
+if echo "$COMMIT_MSG" | grep -q '\[no v\]'; then
+    sed -i "s/^latest-commit-date:.*/latest-commit-date: ${DATE}/" "$YAML_FILE"
+    exit 0
+fi
+
+CURRENT_VERSION=$(grep '^version:' "$YAML_FILE" | awk '{print $2}')
+IFS='.' read -r OLD_MAJOR OLD_MINOR OLD_PATCH <<< "$CURRENT_VERSION"
+
+NEW_MAJOR="$OLD_MAJOR"
+NEW_MINOR="$OLD_MINOR"
+NEW_PATCH="$OLD_PATCH"
+NEW_VERSION=""
+USED_OVERRIDE=0
+
+# Process [vX.Y.Z] version override
+VERSION_OVERRIDE=$(echo "$COMMIT_MSG" | grep -o '\[v[0-9]\+\.[0-9]\+\.[0-9]\+\]' | tr -d '[]v')
+
+if [ -n "$VERSION_OVERRIDE" ]; then
+    USED_OVERRIDE=1
+    if ! echo "$VERSION_OVERRIDE" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+        echo "Error: Invalid version string: [v$VERSION_OVERRIDE]"
+        exit 1
+    fi
+
+    IFS='.' read -r NEW_MAJOR NEW_MINOR NEW_PATCH <<< "$VERSION_OVERRIDE"
+
+    # Reject same version unless [allow same version]
+    if [ "$NEW_MAJOR" -eq "$OLD_MAJOR" ] && [ "$NEW_MINOR" -eq "$OLD_MINOR" ] && [ "$NEW_PATCH" -eq "$OLD_PATCH" ]; then
+        if echo "$COMMIT_MSG" | grep -q '\[allow same version\]'; then
+            echo "Warning: Same version used again [$VERSION_OVERRIDE] (allowed by tag)."
+        else
+            echo "Error: Version $VERSION_OVERRIDE is already current. Use [allow same version] to bypass."
+            exit 1
+        fi
+    fi
+
+    # Reject downgrades
+    if [ "$NEW_MAJOR" -lt "$OLD_MAJOR" ] || \
+       { [ "$NEW_MAJOR" -eq "$OLD_MAJOR" ] && [ "$NEW_MINOR" -lt "$OLD_MINOR" ]; } || \
+       { [ "$NEW_MAJOR" -eq "$OLD_MAJOR" ] && [ "$NEW_MINOR" -eq "$OLD_MINOR" ] && [ "$NEW_PATCH" -lt "$OLD_PATCH" ]; }
+    then
+        echo "Error: Version downgrade is not allowed."
+        echo "Old: $CURRENT_VERSION, New: $VERSION_OVERRIDE"
+        exit 1
+    fi
+
+    # Warn on large jumps
+    MAJOR_DIFF=$((NEW_MAJOR - OLD_MAJOR))
+    MINOR_DIFF=$((NEW_MINOR - OLD_MINOR))
+    PATCH_DIFF=$((NEW_PATCH - OLD_PATCH))
+
+    if [ "$MAJOR_DIFF" -gt 1 ] || [ "$MINOR_DIFF" -gt 1 ] || [ "$PATCH_DIFF" -gt 1 ]; then
+        echo "Warning: Version increase greater than 1:"
+        [ "$MAJOR_DIFF" -gt 1 ] && echo "  Major: $OLD_MAJOR → $NEW_MAJOR"
+        [ "$MINOR_DIFF" -gt 1 ] && echo "  Minor: $OLD_MINOR → $NEW_MINOR"
+        [ "$PATCH_DIFF" -gt 1 ] && echo "  Patch: $OLD_PATCH → $NEW_PATCH"
+    fi
+
+    NEW_VERSION="$NEW_MAJOR.$NEW_MINOR.$NEW_PATCH"
+
+else
+    # Auto semantic bump if tagged
+    BUMP_TAG_COUNT=$(echo "$COMMIT_MSG" | grep -o '\[\(major\|minor\|patch\|bump\)\]' | wc -l)
+
+    if [ "$BUMP_TAG_COUNT" -gt 1 ]; then
+        echo "Warning: Multiple bump tags found. Using highest priority (major > minor > patch > bump)."
+    fi
+
+    if echo "$COMMIT_MSG" | grep -qE '\[major\]|\[bump-major\]'; then
+        NEW_MAJOR=$((OLD_MAJOR+1)); NEW_MINOR=0; NEW_PATCH=0
+    elif echo "$COMMIT_MSG" | grep -qE '\[minor\]|\[bump-minor\]'; then
+        NEW_MINOR=$((OLD_MINOR+1)); NEW_PATCH=0
+    elif echo "$COMMIT_MSG" | grep -qE '\[patch\]|\[bump-patch\]|\[bump\]'; then
+        NEW_PATCH=$((OLD_PATCH+1))
+    else
+        sed -i "s/^latest-commit-date:.*/latest-commit-date: ${DATE}/" "$YAML_FILE"
+        exit 0
+    fi
+    NEW_VERSION="$NEW_MAJOR.$NEW_MINOR.$NEW_PATCH"
+fi
+
+# Apply version update
+sed -i "s/^version:.*/version: $NEW_VERSION/" "$YAML_FILE"
+
+# Update release dates as needed
+if [ "$NEW_MAJOR" != "$OLD_MAJOR" ]; then
+    sed -i "s/^releasedate-major:.*/releasedate-major: $DATE/" "$YAML_FILE"
+fi
+if [ "$NEW_MINOR" != "$OLD_MINOR" ]; then
+    sed -i "s/^releasedate-minor:.*/releasedate-minor: $DATE/" "$YAML_FILE"
+fi
+if [ "$NEW_PATCH" != "$OLD_PATCH" ]; then
+    sed -i "s/^releasedate-patch:.*/releasedate-patch: $DATE/" "$YAML_FILE"
+fi
+
+# Always update latest-commit-date
+sed -i "s/^latest-commit-date:.*/latest-commit-date: ${DATE}/" "$YAML_FILE"
+
+# Stage and commit if changed
+git config --global user.name "github-actions[bot]"
+git config --global user.email "github-actions[bot]@users.noreply.github.com"
+git add "$YAML_FILE"
+if ! git diff --cached --quiet; then
+    git commit -m "[info] Update info.yaml version to $NEW_VERSION"
+    git push
+fi
+
+# Tagging
+TAG="v${NEW_VERSION}"
+if ! git rev-parse "$TAG" >/dev/null 2>&1; then
+    git tag "$TAG"
+    git push origin "$TAG"
+else
+    echo "Tag $TAG already exists."
+fi
+
+echo "NEW_VERSION=$NEW_VERSION" >> "$GITHUB_ENV"

.githooks/post-commit renamed to .githooks/post-commit.disabled

@@ -0,0 +1,19 @@
+name: Custom Versioning and Tagging
+
+on:
+  push:
+    branches:
+      - main  # or your working branch
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # needed for tag creation
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Update version and tag if needed
+        run: .github/scripts/update-version.sh