servala-portal/hack/README.md

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