2026-07-11 22:11:21 +02:00
18 changed files with 715 additions and 3 deletions
@@ -0,0 +1,67 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.gitea/workflows/docs.yml'
+
+vars:
+  HUGO_VERSION: "0.128.2"
+  GEEKDOC_VERSION: "v4.1.1"
+
+jobs:
+  deploy:
+    name: Build and deploy docs
+    runs-on: ubuntu-latest
+    container:
+      image: alpine:latest
+
+    steps:
+      - name: Install tools
+        run: apk add --no-cache curl git tar
+
+      - name: Checkout
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SERVER_URL: ${{ github.server_url }}
+          REPO: ${{ github.repository }}
+        run: |
+          git clone --depth 1 \
+            "$(echo "$SERVER_URL" | sed "s|https://|https://oauth2:${TOKEN}@|")/${REPO}.git" .
+
+      - name: Install Hugo
+        env:
+          HUGO_VERSION: ${{ vars.HUGO_VERSION }}
+        run: |
+          curl -sSL "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz" \
+            | tar xz -C /usr/local/bin hugo
+
+      - name: Download Geekdoc theme
+        env:
+          GEEKDOC_VERSION: ${{ vars.GEEKDOC_VERSION }}
+        run: |
+          mkdir -p docs/themes/geekdoc
+          curl -sSL "https://github.com/thegeeklab/hugo-geekdoc/releases/download/${GEEKDOC_VERSION}/hugo-geekdoc.tar.gz" \
+            | tar xz -C docs/themes/geekdoc
+
+      - name: Build
+        run: hugo --source docs --destination public --minify
+
+      - name: Deploy to pages branch
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SERVER_URL: ${{ github.server_url }}
+          REPO: ${{ github.repository }}
+        run: |
+          cd docs/public
+          git init
+          git config user.email "ci@git.k3nny.fr"
+          git config user.name "Gitea CI"
+          git add .
+          git commit -m "deploy docs $(date +%Y-%m-%dT%H:%M:%SZ)"
+          git push --force \
+            "$(echo "$SERVER_URL" | sed "s|https://|https://oauth2:${TOKEN}@|")/${REPO}.git" \
+            HEAD:gh-pages
@@ -6,3 +6,7 @@ releaser-*
 coverage.out
 coverage.html

+# docs build artifacts (downloaded at build time)
+/docs/themes/
+/docs/public/
+
@@ -3,6 +3,19 @@
 All notable changes to this project will be documented in this file.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

+## [1.5.1] - 2026-07-11
+
+### Added
+
+- **Documentation site** — Hugo + Geekdoc theme; content covers installation, CLI reference, configuration, CI integration, and changelog; deployed to `gh-pages` via Gitea CI on push to `main`
+- **`docs:setup` / `docs:serve` / `docs:build` Taskfile tasks** — `docs:setup` downloads the Geekdoc theme bundle (idempotent); `docs:serve` runs Hugo with live reload; `docs:build` produces a minified static site
+- **`FuzzUpdate`** in `internal/changelog` — fuzzes arbitrary existing file content paired with a commit message, covering the `\n## [` insertion logic and idempotency guard
+- **`FuzzWriteVersion`** in `internal/node` — mirrors `FuzzReplaceProjectVersion` in `internal/maven`; fuzzes arbitrary JSON content with arbitrary old/new version strings
+
+### Changed
+
+- **CLAUDE.md** — new "Fuzzing" section: authoritative table of which packages require fuzz tests and why, list of exempt packages with rationale, seed corpus guidelines
+
 ## [1.5.0] - 2026-07-11

 ### Added
@@ -0,0 +1,96 @@
+# CLAUDE.md — project guidelines for releaser
+
+## Overview
+
+`releaser` is a single-binary Go tool for GitFlow-based release automation. It targets Conventional Commits, versioned release branches (`release/X.Y`), and GitLab / GitHub release creation.
+
+## Architecture
+
+```
+cmd/main.go          — CLI entrypoint (cobra), run() pipeline, verbose output
+internal/branch/     — branch name parser → major/minor
+internal/changelog/  — CHANGELOG.md writer
+internal/commits/    — Conventional Commits parser (non-strict)
+internal/config/     — .releaser.yml loader + env var overlay + source tracking
+internal/ghclient/   — minimal GitHub Releases API client
+internal/gitutil/    — go-git helpers: tag discovery, commit walker, push
+internal/glclient/   — minimal GitLab Releases API client
+internal/maven/      — pom.xml version reader/writer
+internal/node/       — package.json version reader/writer
+internal/notes/      — release notes body generator
+internal/version/    — semver next-version calculator
+```
+
+## Code conventions
+
+- **No third-party test frameworks** — stdlib `testing` only.
+- **No interfaces for mocking** — inject function variables (`var absPath = filepath.Abs`) to test error paths.
+- **No comments explaining what** — only comments explaining *why* (hidden constraints, invariants, non-obvious workarounds).
+- **No error handling for impossible paths** — trust internal invariants; only validate at system boundaries.
+- **No abstractions ahead of need** — three similar lines beats a premature helper.
+
+## Test coverage
+
+**100% per-package statement coverage is required** across all packages. Run:
+
+```bash
+go test ./... -cover
+```
+
+Every package must show `coverage: 100.0% of statements`.
+
+Strategies used in this project:
+- **Error path injection**: override `var absPath`, `var gitAllCommits`, etc. to return injected errors.
+- **Filesystem tricks**: `os.Mkdir` where a file is expected (invisible to go-git dirty check; fails os.WriteFile/os.ReadFile); `os.Chmod(..., 0444)` to make files read-only.
+- **Null byte paths**: `"path\x00name"` causes `os.Stat` to return `EINVAL` (not `ErrNotExist`), useful for testing stat-error paths that differ from file-not-found.
+- **In-memory git repos**: use go-git `PlainInit` + local bare remote for push tests.
+- **Direct function calls**: call unexported helpers (e.g. `printVerboseConfig`) directly with crafted inputs to cover branches that are dead via normal CLI flow.
+
+## Fuzzing
+
+**Every package that parses free-form text or reads/writes arbitrary file content must have at least one fuzz test.** Run the full seed corpus with:
+
+```bash
+go test -run='^Fuzz' ./...
+```
+
+All seed cases must pass. The table below is authoritative — keep it in sync when adding packages or parsers:
+
+| Package | Fuzz target(s) | Why |
+|---------|---------------|-----|
+| `internal/branch` | `FuzzParse` | parses branch name strings |
+| `internal/changelog` | `FuzzUpdate` | rewrites arbitrary existing file content |
+| `internal/commits` | `FuzzParse` | parses arbitrary commit message strings |
+| `internal/glclient` | `FuzzEncodeProjectPath` | encodes arbitrary project path strings |
+| `internal/maven` | `FuzzReadVersion`, `FuzzReplaceProjectVersion` | reads/rewrites arbitrary XML file content |
+| `internal/node` | `FuzzReadVersion`, `FuzzWriteVersion` | reads/rewrites arbitrary JSON file content |
+| `internal/notes` | `FuzzGenerate` | generates notes from arbitrary commit messages |
+
+Packages **not** requiring fuzz tests (no free-form text parsing): `internal/config` (yaml.v3 handles parsing), `internal/ghclient` (HTTP client, no text parsing), `internal/gitutil` (git operations), `internal/version` (typed inputs only), `cmd` (CLI orchestration).
+
+Fuzz seed corpus guidelines:
+- Include a realistic happy-path input as the first seed.
+- Include empty string, binary/non-UTF-8 bytes (`"\x00\xff"`), and inputs that stress known branches (e.g. existing `## [version]` heading for changelog).
+- The fuzz body must never assert on return values — only verify no panic.
+
+## Dependency rules
+
+- **No new external dependencies** unless absolutely necessary. The project deliberately avoids pulling in large ecosystems.
+- go-git (`github.com/go-git/go-git/v5`) for all git operations.
+- cobra for CLI parsing.
+- gopkg.in/yaml.v3 for config.
+
+## Config design
+
+- New config fields go in the appropriate `*Config` struct in `internal/config/config.go`.
+- `defaultSources()` must be updated to include every new key.
+- `LoadWithSources` overlay detection must cover every new field.
+- `printVerboseConfig` in `cmd/main.go` must show every new config value.
+
+## Multi-value config pattern
+
+When a config supports both a single value and multiple values (like `pom_path` / `pom_paths`):
+- Single field: `PomPath string`
+- Multi field: `PomPaths []string`
+- `EffectivePomPaths()` method: `PomPaths` wins if non-empty, else `PomPath` if set, else default.
+- `--pom` CLI flag clears `PomPaths` and sets `PomPath` only.
@@ -1,6 +1,6 @@
 # releaser

-![release](https://img.shields.io/badge/release-v1.5.0-blue.svg)
+![release](https://img.shields.io/badge/release-v1.5.1-blue.svg)

 A CI-friendly release automation tool for GitFlow workflows using Conventional Commits.

@@ -74,7 +74,7 @@
 - [x] ~~GitHub release support~~ — ✓ shipped v1.4.0 (`internal/ghclient`, `GITHUB_TOKEN` env, `github.token`/`github.repo` config; GitHub takes precedence over GitLab)
 - [x] ~~SSH agent push~~ — ✓ shipped v1.4.0 (go-git `gitssh.NewSSHAgentAuth` for `git@`/`ssh://` remotes)
 - [x] ~~Configurable bump rules~~ — ✓ shipped v1.4.0 (`git.releasable_types` config; filter which commit types trigger a release)
- [ ] Documentation site
+- [x] ~~Documentation site~~ — ✓ shipped v1.5.1 (Hugo + Geekdoc; installation, CLI reference, configuration, CI integration pages; deployed via Gitea CI to `gh-pages`)

 ## v1.5 — Multi-module, Node.js, configurable bump rules ✅

@@ -87,4 +87,3 @@

 - Gradle support (`build.gradle` / `build.gradle.kts`)
 - Slack / Teams notification on release
- Documentation site
@@ -4,6 +4,7 @@ vars:
  BIN: ./bin/releaser
  PKG: ./...
  FUZZ_TIME: 30s
+  GEEKDOC_VERSION: "v4.1.1"

 tasks:
  default:
@@ -105,3 +106,23 @@ tasks:
      TAG: '{{.TAG | default "releaser:dev"}}'
    cmds:
      - docker run --rm {{.TAG}} {{.CLI_ARGS}}
+
+  docs:setup:
+    desc: Download Geekdoc theme into docs/themes/geekdoc/
+    cmds:
+      - mkdir -p docs/themes/geekdoc
+      - curl -sSL "https://github.com/thegeeklab/hugo-geekdoc/releases/download/{{.GEEKDOC_VERSION}}/hugo-geekdoc.tar.gz" | tar xz -C docs/themes/geekdoc
+    status:
+      - test -f docs/themes/geekdoc/theme.toml
+
+  docs:serve:
+    desc: Serve docs locally with live reload (requires hugo)
+    deps: [docs:setup]
+    cmds:
+      - hugo server --source docs
+
+  docs:build:
+    desc: Build docs to docs/public/ (requires hugo)
+    deps: [docs:setup]
+    cmds:
+      - hugo --source docs --destination public --minify
@@ -0,0 +1,24 @@
+---
+title: releaser
+---
+
+**CI-friendly release automation for GitFlow workflows using Conventional Commits.**
+
+Standard tools like `semantic-release` are designed for trunk-based development. In a GitFlow setup with versioned release branches (`release/1.1`, `release/1.2`), they either fail to respect the branch's version range or require brittle configuration.
+
+`releaser` is built for this exact workflow: it reads the branch name to pin the `major.minor`, parses Conventional Commits to determine the patch increment, and handles everything from `pom.xml` / `package.json` update to GitLab/GitHub tag and release creation.
+
+## How it works
+
+```
+release/1.2 branch
+  └─ last tag: 1.2.3 (or none → start at 1.2.0)
+       └─ commits since tag → Conventional Commits analysis
+            └─ next version: 1.2.4
+```
+
+1. **Branch parsing** — extracts `major.minor` from branch name (`release/1.2` → `1.2`)
+2. **Tag discovery** — finds the latest tag matching `major.minor.*` on the current branch
+3. **Commit analysis** — parses Conventional Commits between last tag and HEAD
+4. **Version bump** — increments patch (or minor, if configured via `bump_rules`)
+5. **Release** — updates `pom.xml` / `package.json`, commits, tags, creates GitLab or GitHub release
@@ -0,0 +1,59 @@
+---
+title: Changelog
+weight: 50
+---
+
+## v1.5.0 — 2026-07-11
+
+### Added
+
+- **Multi-module Maven support** — `maven.pom_paths: [...]` lists multiple `pom.xml` paths; overrides `pom_path`; each path is updated and committed in the same release commit
+- **Node.js `package.json` support** — opt-in via `node.package_json` (single path) or `node.package_jsons` (list); version bumped in-place alongside `pom.xml` and `CHANGELOG.md`
+- **`git.bump_rules` config** — controls which version component each commit type bumps: `breaking`, `feat`, `fix` each accept `"patch"` (default) or `"minor"`
+- **100% per-package statement coverage** across all 12 packages via injectable function vars
+
+### Changed
+
+- **`--pom` flag** now clears `maven.pom_paths` before setting `maven.pom_path`
+- **`version.Next()` signature** — accepts a bump-rules map as a sixth parameter; `nil` defaults to all-patch
+- **Verbose config table** — now includes `git.bump_rules.*`, `maven.pom_paths`, and `node.paths` rows
+
+## v1.4.0 — 2026-07-11
+
+### Added
+
+- **GitHub release support** — `internal/ghclient` package; configured via `github.token` + `github.repo`; GitHub takes precedence over GitLab when both are configured
+- **SSH agent push** — go-git `gitssh.NewSSHAgentAuth` for `git@` / `ssh://` remotes
+- **`--release-env-file` flag** — override dotenv artifact path; pass `""` to disable
+- **`git.releasable_types` config** — opt-in list of commit types that count as releasable
+- **CHANGELOG deduplication guard** — `changelog.Update()` is idempotent; skips write if section already exists
+
+## v1.3.0 — 2026-07-07
+
+### Added
+
+- **`release.env` dotenv artifact** — written on every real release containing `NEXT_VERSION=<tag>`; never committed; exposes the version to downstream GitLab CI jobs
+
+## v1.2.0 — 2026-07-07
+
+### Added
+
+- **`--verbose` flag** — prints config table, commit list with parsed types, and version decision
+- **Colored, structured CLI output** — `·` / `✓` / `!` prefix symbols; TTY-aware ANSI colors; respects `NO_COLOR` and `TERM=dumb`
+- **Name and version header** on every invocation
+
+### Changed
+
+- **Default `tag_prefix` is now empty** — bare version numbers (`1.2.3`) by default; add `tag_prefix: "v"` to opt in
+
+## v1.1.0 — 2026-07-07
+
+### Added
+
+- **CHANGELOG.md auto-update** — new dated section written on every release, grouped by commit type
+- **`--changelog-file` flag** — override changelog path
+- **`--init` flag** — scaffolds a fully-commented `.releaser.yml`
+
+## v1.0 and earlier
+
+See the [full CHANGELOG](https://git.k3nny.fr/releaser/src/branch/main/CHANGELOG.md) in the repository.
@@ -0,0 +1,109 @@
+---
+title: CI Integration
+weight: 40
+---
+
+## GitLab CI
+
+The simplest setup uses the reusable job template shipped alongside `releaser`:
+
+```yaml
+# .gitlab-ci.yml
+include:
+  - project: releaser/releaser
+    file: .releaser.gitlab-ci.yml
+
+release:
+  extends: .releaser
+  variables:
+    GITLAB_TOKEN: $RELEASE_TOKEN   # project/group variable with api + write_repository scope
+```
+
+Or write it inline:
+
+```yaml
+release:
+  stage: release
+  image: registry.example.com/releaser:latest
+  rules:
+    - if: $CI_COMMIT_BRANCH =~ /^release\/.+$/
+  variables:
+    GITLAB_TOKEN: $RELEASE_TOKEN
+  script:
+    - releaser
+  artifacts:
+    reports:
+      dotenv: release.env          # exposes NEXT_VERSION to downstream jobs
+```
+
+### Consuming `NEXT_VERSION` downstream
+
+The `release.env` dotenv artifact exports `NEXT_VERSION=<tag>` automatically. Downstream jobs can use it:
+
+```yaml
+deploy:
+  stage: deploy
+  needs:
+    - job: release
+      artifacts: true
+  script:
+    - echo "Deploying version $NEXT_VERSION"
+```
+
+Disable the dotenv artifact (e.g. for local runs):
+
+```bash
+releaser --release-env-file ""
+```
+
+Write it to a custom path:
+
+```bash
+releaser --release-env-file deploy/version.env
+```
+
+## GitHub Actions / Gitea Actions
+
+```yaml
+name: release
+on:
+  push:
+    branches:
+      - 'release/**'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # full history needed for tag discovery
+
+      - name: Run releaser
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          curl -sSL https://git.k3nny.fr/releaser/releases/latest/download/releaser-linux-amd64 \
+            -o /usr/local/bin/releaser
+          chmod +x /usr/local/bin/releaser
+          releaser
+```
+
+{{< hint warning >}}
+`fetch-depth: 0` is required. A shallow clone (`--depth 1`) hides the previous tag, causing `releaser` to treat every commit as the first release.
+{{< /hint >}}
+
+## Detached HEAD
+
+In CI environments where `git checkout` leaves the repository in detached HEAD state, pass the branch name explicitly:
+
+```yaml
+script:
+  - releaser --branch "$CI_COMMIT_BRANCH"
+```
+
+## SSH push
+
+When pushing over SSH (`git@host:...` or `ssh://...` remotes), `releaser` attempts go-git SSH agent auth automatically — no extra configuration needed as long as the CI runner has an SSH agent socket available.
+
+For HTTPS remotes without a token, `releaser` delegates to the system `git` binary so credential helpers and `netrc` work as expected.
@@ -0,0 +1,121 @@
+---
+title: Configuration
+weight: 30
+---
+
+`releaser` reads `.releaser.yml` from the repository root. All fields are optional — missing values fall back to the defaults shown below. Run `releaser --init` to scaffold the file with annotations.
+
+## Full reference
+
+```yaml
+git:
+  tag_prefix: ""                                     # default: no prefix; "v" for v1.2.3 style
+  branch_pattern: "^(?:.*/)?release/(\\d+)\\.(\\d+)$"  # two capture groups: major, minor
+  commit_message: "chore(release): {version} [skip ci]"
+  author_name: ""                                    # defaults to git config user.name
+  author_email: ""                                   # defaults to git config user.email
+
+  # Limit which commit types trigger a release (default: all three).
+  releasable_types:
+    - fix
+    - feat
+    - breaking
+
+  # Control which version component each commit type bumps.
+  # Valid values: "patch" (default) or "minor".
+  bump_rules:
+    breaking: "patch"
+    feat: "patch"
+    fix: "patch"
+
+maven:
+  pom_path: "pom.xml"                                # single pom.xml, relative to repo root
+
+  # Multi-module: list overrides pom_path.
+  # pom_paths:
+  #   - "pom.xml"
+  #   - "module-a/pom.xml"
+  #   - "module-b/pom.xml"
+
+node:                                                # opt-in — omit section to skip
+  # package_json: "package.json"                     # single path
+
+  # Monorepo: list overrides package_json.
+  # package_jsons:
+  #   - "packages/frontend/package.json"
+  #   - "packages/backend/package.json"
+
+gitlab:
+  url: "https://gitlab.example.com"                  # or env CI_SERVER_URL
+  token: ""                                          # prefer env GITLAB_TOKEN
+  project: ""                                        # prefer env CI_PROJECT_ID or CI_PROJECT_PATH
+
+github:
+  token: ""                                          # prefer env GITHUB_TOKEN
+  repo: ""                                           # "owner/repo" format
+```
+
+{{< hint info >}}
+When both `github.*` and `gitlab.*` are configured, GitHub takes precedence.
+{{< /hint >}}
+
+## Environment variables
+
+| Variable | Used for |
+|----------|----------|
+| `GITLAB_TOKEN` | GitLab API auth + HTTPS push auth |
+| `CI_SERVER_URL` | GitLab instance URL |
+| `CI_PROJECT_ID` | GitLab project identifier (numeric) |
+| `CI_PROJECT_PATH` | GitLab project identifier (fallback) |
+| `GITHUB_TOKEN` | GitHub API auth |
+
+## Config sources
+
+Run `releaser --verbose --dry-run` to see every config key, its resolved value, and where it came from (`default` / `config file` / `env: VARNAME` / `flag: --name`).
+
+## `git.releasable_types`
+
+By default `fix`, `feat`, and `breaking` commits all trigger a release. Use `releasable_types` to restrict this — for example, on a maintenance branch where you want only bug fixes to release:
+
+```yaml
+git:
+  releasable_types:
+    - fix
+```
+
+## `git.bump_rules`
+
+By default every releasable commit bumps the **patch** component. The `bump_rules` map lets you promote specific types to bump **minor** instead. This is useful on a branch that manages its own minor versioning:
+
+```yaml
+git:
+  bump_rules:
+    feat: "minor"      # feat: commits bump minor, not patch
+    breaking: "minor"  # breaking changes bump minor too
+    fix: "patch"       # fix: stays patch (this is the default)
+```
+
+## Multi-module Maven
+
+`pom_paths` accepts a list and overrides `pom_path`. All listed files are updated and committed in the same release commit:
+
+```yaml
+maven:
+  pom_paths:
+    - "pom.xml"
+    - "module-a/pom.xml"
+    - "module-b/pom.xml"
+```
+
+The `--pom` CLI flag sets a single path and clears `pom_paths`.
+
+## Node.js support
+
+The `node` section is opt-in — if omitted, no `package.json` is touched. Use `package_jsons` for monorepos:
+
+```yaml
+node:
+  package_jsons:
+    - "packages/frontend/package.json"
+    - "packages/backend/package.json"
+```
@@ -0,0 +1,59 @@
+---
+title: Installation
+weight: 10
+---
+
+## Pre-built binaries
+
+Download the latest release for your platform from the [Releases page](https://git.k3nny.fr/releaser/releases).
+
+```bash
+# Linux (amd64)
+curl -sSL https://git.k3nny.fr/releaser/releases/download/v1.5.0/releaser-v1.5.0-linux-amd64 \
+  -o /usr/local/bin/releaser
+chmod +x /usr/local/bin/releaser
+```
+
+Available platforms: `linux-amd64`, `linux-arm64`, `darwin-amd64`, `darwin-arm64`, `windows-amd64.exe`.
+
+## Docker
+
+```bash
+docker pull git.k3nny.fr/releaser/releaser:latest
+
+# Run in the current repository
+docker run --rm \
+  -v "$PWD:/repo" \
+  -e GITLAB_TOKEN="$GITLAB_TOKEN" \
+  git.k3nny.fr/releaser/releaser:latest
+```
+
+## Build from source
+
+Requires Go 1.21+.
+
+```bash
+git clone https://git.k3nny.fr/releaser/releaser.git
+cd releaser
+go build -o /usr/local/bin/releaser ./cmd
+```
+
+## Verify
+
+```bash
+releaser --version
+```
+
+## First run
+
+Scaffold a default `.releaser.yml` in your repository root:
+
+```bash
+releaser --init
+```
+
+Then do a dry run to check the version that would be produced:
+
+```bash
+releaser --dry-run
+```
@@ -0,0 +1,69 @@
+---
+title: CLI Reference
+weight: 20
+---
+
+## Common workflows
+
+```bash
+# Scaffold a default .releaser.yml
+releaser --init
+
+# Preview next version (no side effects)
+releaser --dry-run
+
+# Full release: bump versions, commit, tag, push, create release
+releaser
+
+# Commit and tag locally — skip push and release creation
+releaser --no-push
+
+# Push commit and tag but skip creating the release
+releaser --no-release
+
+# Update files but stop before committing
+releaser --no-commit
+# ... review changes, then commit manually and re-run:
+releaser --tag-only
+
+# Verbose mode: show config sources, commit analysis, version decision
+releaser --verbose --dry-run
+```
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--dry-run` | false | Print next version and exit without making any changes |
+| `--branch <name>` | auto-detected | Override branch name (useful in detached HEAD / CI) |
+| `--branch-pattern <regex>` | `^(?:.*/)?release/(\d+)\.(\d+)$` | Override branch pattern (two capture groups: major, minor) |
+| `--tag-prefix <prefix>` | `""` | Prefix for version tags (e.g. `v` → `v1.2.3`) |
+| `--pom <path>` | `pom.xml` | Path to pom.xml relative to repo root |
+| `--changelog-file <path>` | `CHANGELOG.md` | Path to changelog file |
+| `--release-env-file <path>` | `release.env` | Path for dotenv artifact; pass `""` to disable |
+| `--no-commit` | false | Update version files but stop before committing |
+| `--no-push` | false | Commit and tag locally, skip push and release |
+| `--no-release` | false | Push branch and tag but skip release creation |
+| `--tag-only` | false | Skip version file updates — tag HEAD and push |
+| `--init` | false | Scaffold a default `.releaser.yml` and exit |
+| `--verbose` | false | Print config table, commit analysis, and version decision |
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Error (config, git, API, etc.) |
+| `2` | No releasable commits found — nothing to do |
+
+## Version bump rules
+
+By default all releasable commits bump the **patch** component (minor is pinned to the branch). Override per commit type via `git.bump_rules` in `.releaser.yml`:
+
+| Commit type | Default | Configurable via `bump_rules` |
+|-------------|---------|-------------------------------|
+| `fix:` | patch | `fix: "minor"` to bump minor |
+| `feat:` | patch | `feat: "minor"` to bump minor |
+| `feat!:` / `BREAKING CHANGE` | patch | `breaking: "minor"` to bump minor |
+| `chore:`, `docs:`, etc. | none | — |
+| unparseable message | none | non-strict: silently ignored |
@@ -0,0 +1,16 @@
+main:
+  - name: Installation
+    ref: /installation
+    weight: 10
+  - name: CLI Reference
+    ref: /usage
+    weight: 20
+  - name: Configuration
+    ref: /configuration
+    weight: 30
+  - name: CI Integration
+    ref: /ci-integration
+    weight: 40
+  - name: Changelog
+    ref: /changelog
+    weight: 50
@@ -0,0 +1,21 @@
+baseURL = "/"
+title = "releaser"
+theme = "geekdoc"
+
+pygmentsUseClasses = true
+pygmentsCodeFences = true
+
+[markup]
+  [markup.goldmark.renderer]
+    unsafe = true
+  [markup.tableOfContents]
+    startLevel = 1
+    endLevel = 9
+
+[params]
+  geekdocRepo = "https://git.k3nny.fr/releaser"
+  geekdocEditPath = "edit/main/docs/content"
+  geekdocSearch = true
+  geekdocMenuBundle = true
+  geekdocBreadcrumb = false
+  geekdocToC = true
@@ -149,3 +149,22 @@ func TestUpdateIdempotent(t *testing.T) {
 		t.Error("version heading should appear exactly once after idempotent call")
 	}
 }
+
+// FuzzUpdate verifies Update never panics on arbitrary existing file content or commit messages.
+func FuzzUpdate(f *testing.F) {
+	f.Add("", "feat: add thing")
+	f.Add("# Changelog\n\n## [1.0.0] - 2026-01-01\n\n### Added\n- something\n", "fix: something")
+	f.Add("some preamble\n", "feat!: breaking change")
+	f.Add("\n## [2.0.0] - 2026-01-01\n", "feat: another thing")
+	f.Add("", "chore: no release")
+	f.Add("", "")
+
+	f.Fuzz(func(t *testing.T, existing, message string) {
+		dir := t.TempDir()
+		path := filepath.Join(dir, "CHANGELOG.md")
+		if existing != "" {
+			os.WriteFile(path, []byte(existing), 0644) //nolint:errcheck
+		}
+		Update(path, "v1.0.0", "1.0.0", []string{message}) //nolint:errcheck
+	})
+}
@@ -82,6 +82,21 @@ func TestWriteVersionNotFound(t *testing.T) {
 	}
 }

+// FuzzWriteVersion verifies WriteVersion never panics on arbitrary content or version strings.
+func FuzzWriteVersion(f *testing.F) {
+	f.Add(simplePackage, "1.2.3", "1.2.4")
+	f.Add(`{"version":"0.0.1"}`, "0.0.1", "0.0.2")
+	f.Add(`{}`, "1.0.0", "1.0.1")
+	f.Add("", "1.0.0", "1.0.1")
+	f.Add(`{"name":"app","version":"1.0.0","version":"dup"}`, "1.0.0", "1.0.1")
+
+	f.Fuzz(func(t *testing.T, content, oldVersion, newVersion string) {
+		path := filepath.Join(t.TempDir(), "package.json")
+		os.WriteFile(path, []byte(content), 0644) //nolint:errcheck
+		WriteVersion(path, oldVersion, newVersion) //nolint:errcheck
+	})
+}
+
 // FuzzReadVersion verifies ReadVersion never panics on arbitrary content.
 func FuzzReadVersion(f *testing.F) {
 	f.Add(simplePackage)