servala-portal/hack

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:

export FORGEJO_TOKEN="your-token-here"

For permanent setup, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.):

echo 'export FORGEJO_TOKEN="your-token-here"' >> ~/.bashrc

3. Update pyproject.toml

Update the bumpver configuration in pyproject.toml to use these hooks:

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

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

# Generate changelog (run before committing)
./hack/pre-commit-hook.sh

# Create release (run after committing and tagging)
./hack/post-commit-hook.sh