From e2d421440558fc4d07d7d115721d83bceda1aaa3 Mon Sep 17 00:00:00 2001 From: k3nny Date: Sat, 11 Jul 2026 17:47:26 +0200 Subject: [PATCH] =?UTF-8?q?docs(releaser):=20release=20v1.5.1=20=E2=80=94?= =?UTF-8?q?=20documentation=20site,=20fuzzing=20completeness?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .gitea/workflows/docs.yml | 67 +++++++++++++++ .gitignore | 4 + CHANGELOG.md | 13 +++ CLAUDE.md | 96 +++++++++++++++++++++ README.md | 2 +- ROADMAP.md | 3 +- Taskfile.yml | 21 +++++ docs/.hugo_build.lock | 0 docs/content/_index.md | 24 ++++++ docs/content/changelog.md | 59 +++++++++++++ docs/content/ci-integration.md | 109 ++++++++++++++++++++++++ docs/content/configuration.md | 121 +++++++++++++++++++++++++++ docs/content/installation.md | 59 +++++++++++++ docs/content/usage.md | 69 +++++++++++++++ docs/data/menu/main.yaml | 16 ++++ docs/hugo.toml | 21 +++++ internal/changelog/changelog_test.go | 19 +++++ internal/node/node_test.go | 15 ++++ 18 files changed, 715 insertions(+), 3 deletions(-) create mode 100644 .gitea/workflows/docs.yml create mode 100644 CLAUDE.md create mode 100644 docs/.hugo_build.lock create mode 100644 docs/content/_index.md create mode 100644 docs/content/changelog.md create mode 100644 docs/content/ci-integration.md create mode 100644 docs/content/configuration.md create mode 100644 docs/content/installation.md create mode 100644 docs/content/usage.md create mode 100644 docs/data/menu/main.yaml create mode 100644 docs/hugo.toml diff --git a/.gitea/workflows/docs.yml b/.gitea/workflows/docs.yml new file mode 100644 index 0000000..728585f --- /dev/null +++ b/.gitea/workflows/docs.yml @@ -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 diff --git a/.gitignore b/.gitignore index ba37d26..78ec88e 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,7 @@ releaser-* coverage.out coverage.html +# docs build artifacts (downloaded at build time) +/docs/themes/ +/docs/public/ + diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b6d725..9f204e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..194bbbd --- /dev/null +++ b/CLAUDE.md @@ -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. diff --git a/README.md b/README.md index 3c2257b..ce79404 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/ROADMAP.md b/ROADMAP.md index d7c2fc1..47c35e0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -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 diff --git a/Taskfile.yml b/Taskfile.yml index 3b39f4d..6feb026 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -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 diff --git a/docs/.hugo_build.lock b/docs/.hugo_build.lock new file mode 100644 index 0000000..e69de29 diff --git a/docs/content/_index.md b/docs/content/_index.md new file mode 100644 index 0000000..3ef18ba --- /dev/null +++ b/docs/content/_index.md @@ -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 diff --git a/docs/content/changelog.md b/docs/content/changelog.md new file mode 100644 index 0000000..4a327a9 --- /dev/null +++ b/docs/content/changelog.md @@ -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=`; 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. diff --git a/docs/content/ci-integration.md b/docs/content/ci-integration.md new file mode 100644 index 0000000..bee2dde --- /dev/null +++ b/docs/content/ci-integration.md @@ -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=` 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. diff --git a/docs/content/configuration.md b/docs/content/configuration.md new file mode 100644 index 0000000..dc58d47 --- /dev/null +++ b/docs/content/configuration.md @@ -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" +``` diff --git a/docs/content/installation.md b/docs/content/installation.md new file mode 100644 index 0000000..55a429b --- /dev/null +++ b/docs/content/installation.md @@ -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 +``` diff --git a/docs/content/usage.md b/docs/content/usage.md new file mode 100644 index 0000000..71dd12b --- /dev/null +++ b/docs/content/usage.md @@ -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 ` | auto-detected | Override branch name (useful in detached HEAD / CI) | +| `--branch-pattern ` | `^(?:.*/)?release/(\d+)\.(\d+)$` | Override branch pattern (two capture groups: major, minor) | +| `--tag-prefix ` | `""` | Prefix for version tags (e.g. `v` → `v1.2.3`) | +| `--pom ` | `pom.xml` | Path to pom.xml relative to repo root | +| `--changelog-file ` | `CHANGELOG.md` | Path to changelog file | +| `--release-env-file ` | `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 | diff --git a/docs/data/menu/main.yaml b/docs/data/menu/main.yaml new file mode 100644 index 0000000..ed3c95e --- /dev/null +++ b/docs/data/menu/main.yaml @@ -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 diff --git a/docs/hugo.toml b/docs/hugo.toml new file mode 100644 index 0000000..8aa4cdb --- /dev/null +++ b/docs/hugo.toml @@ -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 diff --git a/internal/changelog/changelog_test.go b/internal/changelog/changelog_test.go index f9112a5..35070f0 100644 --- a/internal/changelog/changelog_test.go +++ b/internal/changelog/changelog_test.go @@ -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 + }) +} diff --git a/internal/node/node_test.go b/internal/node/node_test.go index 456a804..a1ad82b 100644 --- a/internal/node/node_test.go +++ b/internal/node/node_test.go @@ -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)