add changelog tooling

hack/README.md

@@ -0,0 +1,116 @@
+# Automation Scripts
+
+This directory contains automation scripts for release management and changelog generation.
+
+## Scripts
+
+### bumpver-pre-commit-hook.sh
+
+**Purpose**: Generates a changelog based on merged Pull Requests since the last release.
+
+**What it does**:
+1. Queries the Forgejo API for merged pull requests since the last release tag
+2. Groups pull requests by their labels (first label if multiple labels are present)
+3. Formats the changes in AsciiDoc format with third-level headers for each label group
+4. Appends the changelog to `docs/modules/ROOT/pages/web-portal-changelog.adoc`
+5. Adds the changelog file to git staging area
+6. Saves the changelog content for the post-commit hook
+
+**Note**: Pull requests without labels will be grouped under "Uncategorized".
+
+**Requirements**:
+- `FORGEJO_TOKEN` environment variable must be set with a valid Forgejo API token
+- `jq` command-line JSON processor must be installed
+- `curl` must be installed
+
+### bumpver-post-commit-hook.sh
+
+**Purpose**: Creates a release on Forgejo after a version bump.
+
+**What it does**:
+1. Gets the current version from `pyproject.toml`
+2. Reads the changelog content generated by the pre-commit hook
+3. Converts AsciiDoc format to Markdown (headers and links)
+4. Creates or updates a release on Forgejo with the Markdown-formatted changelog
+5. Cleans up temporary changelog files
+
+**Note**: The script automatically converts AsciiDoc syntax to Markdown for Forgejo releases:
+- `=== Header` → `### Header`
+- `link:url[text]` → `[text](url)`
+
+**Requirements**:
+- `FORGEJO_TOKEN` environment variable must be set with a valid Forgejo API token
+- `jq` command-line JSON processor must be installed
+- `curl` must be installed
+
+## Setup
+
+### 1. Generate a Forgejo API Token
+
+1. Log in to Forgejo at https://servala.app.codey.ch
+2. Go to Settings → Applications → Generate New Token
+3. Give it a descriptive name (e.g., "bumpver-automation")
+4. Select the required permissions:
+   - `repo` (Full control of repositories)
+5. Copy the generated token
+
+### 2. Configure the token
+
+Export the token as an environment variable:
+
+```bash
+export FORGEJO_TOKEN="your-token-here"
+```
+
+For permanent setup, add it to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
+
+```bash
+echo 'export FORGEJO_TOKEN="your-token-here"' >> ~/.bashrc
+```
+
+### 3. Update pyproject.toml
+
+Update the bumpver configuration in `pyproject.toml` to use these hooks:
+
+```toml
+[tool.bumpver]
+current_version = "2025.10.27-0"
+version_pattern = "YYYY.0M.0D-INC0"
+commit_message = "bump version {old_version} -> {new_version}"
+tag_message = "{new_version}"
+tag_scope = "default"
+pre_commit_hook = "hack/bumpver-pre-commit-hook.sh"
+post_commit_hook = "hack/bumpver-post-commit-hook.sh"
+commit = true
+tag = true
+push = true
+```
+
+## Usage
+
+Once configured, the hooks will run automatically when you bump the version:
+
+```bash
+# Or let bumpver determine the version based on the pattern
+uvx bumpver update
+```
+
+The workflow is:
+1. `bumpver` updates version files
+2. **Pre-commit hook** runs: generates changelog, updates changelog file, stages changes
+3. `bumpver` creates commit with version bump and changelog
+4. `bumpver` creates git tag
+5. **Post-commit hook** runs: creates Forgejo release
+6. `bumpver` pushes commit and tags to remote
+
+## Manual execution
+
+You can also run the scripts manually:
+
+```bash
+# Generate changelog (run before committing)
+./hack/pre-commit-hook.sh
+
+# Create release (run after committing and tagging)
+./hack/post-commit-hook.sh
+```