Release And Versioning

Release and Versioning

Follow the repository scope. Version edits, dependency refreshes, commits, tags, and publication apply only to caddy-security. Read sibling versions/history as inputs; do not bump, sync, fetch into, tag, or release a sibling to unblock this module. Missing upstream releases are separate work. Keep chosen snapshot and report destinations here.

Version Authority

VERSION owns the caddy-security release number. Preserve the existing 1.<minor>.<patch> release line, with no v in the file and v<VERSION> for the Git tag. A feature change or dependency update alone does not request a version bump or publication. Read current values from the checkout instead of copying versions from examples or the sibling repository.

Keep these version surfaces distinct:

• Makefile reads VERSION into PLUGIN_VERSION; release recipes read it again for the commit subject and annotated tag.
• assets/scripts/generate_downloads.sh projects VERSION into README Caddy download URLs. It separately hard-codes the caddy-trace version. Verify its Download Caddy with the plugins enabled insertion marker exists before regenerating links, and inspect their placement afterward. The macOS branch requires gsed as well as BSD sed.
• go.mod selects the go-authcrunch dependency version; ../go-authcrunch/VERSION is the sibling library's release number. Neither sets this module's version. make sync updates dependency references and removes local replacements; it is a separate dependency refresh, not caddy-security version synchronization.
• cmd/authcrunch/main.go delegates to Caddy. It has no application version fallback declarations to synchronize. The Makefile does not inject its PLUGIN_VERSION with linker flags, so bin/authcrunch version alone does not establish this module's release identity.
• bin/authcrunch security version reads the linked go-authcrunch module from embedded Go build metadata. It retains pseudo-versions and shows replacements, including (devel) for unversioned local paths. This is dependency identity, distinct from Caddy's version and this repository's release number; see security dependency version.
• cmd/caddy-authenticator/main.go initializes *versioned.PackageManager with a literal fallback for ordinary go install builds. make build injects VERSION into main.appVersion; caddy-authenticator version prints its banner. GoReleaser builds separate platform archives and injects release/snapshot version, commit and build metadata; see CI and packaging. Keep the fallback synchronized using make version-sync after an explicit VERSION change. Sync validates VERSION first and changes only the existing fallback; it neither bumps the release nor stages files.

make version-check validates the fixed-major namespace through assets/scripts/version.py without rewriting files. It accepts a single optional trailing newline, rejects leading zeros and prerelease/build suffixes, and bounds components for versioned. check --tag additionally requires the exact v<VERSION> tag. It does not validate README link placement or contents. The check also rejects a missing, ambiguous or stale authenticator fallback; artifact identity validation enforces the same consistency without rewriting it.

make artifact-id validates the version and produces v<VERSION>_<UTC YYYYMMDDTHHMMSSZ>_<12-character SHA> for branch/PR/manual builds. An exact v<VERSION> tag produces v<VERSION>; another tag fails. GITHUB_SHA provides the checked CI revision (including PR merge commits), with local HEAD as fallback. Validated version and artifact_id values go to GITHUB_OUTPUT.

make release increments the patch; make minor-release increments the minor and resets the patch to zero. Both preserve the major release line. assets/scripts/version.py next --kind patch|minor computes the candidate without writing files and rejects an increment beyond the supported range. version-sync projects VERSION into the authenticator fallback only.

Existing Release Targets

Read the current Makefile before executing release operations. The targets have different side effects:

The shared script serializes checks, bump, synchronization, download generation, make ci-check, commit, tag, and push even under parallel Make. It requires main with no tracked, staged, or untracked changes, fetches origin/main, rejects behind/diverged history and an existing candidate tag locally or on origin, and checks the README marker and macOS gsed prerequisite before bumping. The pinned go tool versioned command comes from go.mod; release operations do not depend on a globally installed versioned executable.

For regular releases, the gate runs once against the bumped version, including the binary build. Fast releases skip the entire local gate (automation tests, Go tests/reports, and build); GitHub release validation still runs before GoReleaser publication. All version/Git checks, synchronization, download generation, staging restrictions and atomic publication remain in place. Use a fast target only when the user requests it; release-git-check does not accept --skip-tests. Only VERSION, README.md, and cmd/caddy-authenticator/main.go are staged. Unexpected staged, other tracked, or untracked changes stop publication. The commit subject is ops: released v<VERSION> and the exact tag is annotated. One atomic push publishes HEAD:refs/heads/main and that tag to origin; unrelated local tags are excluded. There is no fallback to separate pushes.