docs(releaser): release v1.5.1 — documentation site, fuzzing completeness
ci / vet, staticcheck, test, build (push) Failing after 3m50s
ci / vet, staticcheck, test, build (push) Failing after 3m50s
- Add Hugo + Geekdoc documentation site (docs/): installation, CLI reference, configuration, CI integration, and changelog pages; explicit menu bundle nav so all pages appear in the sidebar on every page - Add Gitea CI workflow (.gitea/workflows/docs.yml): builds on push to main when docs/** changes, deploys minified site to gh-pages branch - Add docs:setup / docs:serve / docs:build Taskfile tasks; theme bundle downloaded at build time (not committed) - Add FuzzUpdate to internal/changelog and FuzzWriteVersion to internal/node to complete fuzz coverage for all file-rewriting packages - Add fuzzing completeness guidelines to CLAUDE.md: authoritative table, exempt-package rationale, seed corpus rules Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -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 |
|
||||
Reference in New Issue
Block a user