vociferate/README.md

vociferate

A reusable release preparation tool for Go repositories.

Build

Build with just:

just go-build

Or directly with Go:

go build -o dist/vociferate ./cmd/vociferate

Usage

Prepare release files:

go run ./cmd/vociferate --version v1.2.3 --date 2026-03-20 --root .

In the provided workflow and composite action, version is optional. When it is omitted, vociferate computes and uses the recommended next version automatically.

Recommend next release tag from changelog content:

go run ./cmd/vociferate --recommend --root .

Flags

• --version semantic version to release (with or without leading v).
• --date release date in YYYY-MM-DD format.
• --recommend print recommended next tag based on ## [Unreleased].
• --root repository root directory.
• --version-file path to version source file relative to --root.
• --version-pattern regexp with exactly one capture group for version value.
• --changelog path to changelog file relative to --root.

Defaults:

• version-file: release-version
• version-pattern: ^\s*([^\r\n]+)\s*$
• changelog: changelog.md

By default, vociferate reads and writes the release version as the sole content of a root-level release-version file. Repositories that keep the version inside source code should pass explicit version-file and version-pattern values.

Testing

just go-test

Release Artifacts

Releases are prepared through the Prepare Release workflow. The workflow creates a release and uploads prebuilt vociferate binaries for:

• linux/amd64
• linux/arm64

It also uploads checksums.txt for integrity verification. If a release already exists for the same tag, the workflow updates its release notes and replaces matching asset filenames so reruns stay in sync.

Reuse In Other Repositories

You can reuse vociferate in two ways.

Use the composite action directly:

- name: Prepare release files
	uses: git.hrafn.xyz/aether/vociferate@v1.0.0
	with:
		version-file: internal/myapp/version/version.go
		version-pattern: 'const Version = "([^"]+)"'
		changelog: changelog.md

Set version only when you want to override the recommended version. Pin the composite action to a released tag. It downloads a prebuilt Linux binary from vociferate releases and caches it on the runner, so it does not require installing Go. If your repository uses the default plain-text release-version file, you can omit version-file and version-pattern entirely.

Call the reusable release workflow:

name: Release

on:
	workflow_dispatch:
		inputs:
			version:
				description: Optional semantic version override.
				required: false

jobs:
	release:
		uses: aether/vociferate/.gitea/workflows/prepare-release.yml@main
		with:
			version: ${{ inputs.version }}
		secrets: inherit