devopsfactory-io/release-and-versioning

Release and Versioning

Semantic Versioning

• Tags use the form vMAJOR.MINOR.PATCH (e.g. v0.2.0, v1.0.0).
• The v prefix is required for the release workflow. Do not add a version in go.mod for release; the binary gets version from ldflags at build time.

Release Steps

1. Ensure main is green – CI (test, lint) must pass on the branch you will tag.
2. Create and push the tag:
   • git tag vX.Y.Z
   • git push origin vX.Y.Z
3. Let CI run – .github/workflows/release.yml runs on tag push. GoReleaser creates the GitHub Release with neptune binaries (lowercase archives e.g. neptune_linux_amd64.tar.gz and raw binaries), neptune-webhook.zip and raw neptune-webhook_linux_amd64 (Lambda binary is neptune-webhook), checksums, and release notes. The release body is generated by GitHub (changelog.use: github-native) and categorized by .github/release.yml and PR labels.
4. Do not run destructive commands (e.g. git push or creating tags) without user confirmation.

GoReleaser

• .goreleaser.yml: Builds neptune from the repo root (ldflags set main.version, main.commit, main.date) and Lambda neptune-webhook from lambda/ (released as neptune-webhook.zip and raw neptune-webhook_linux_amd64). Produces lowercase-named archives (e.g. neptune_linux_amd64.tar.gz), raw binaries, and checksums. With changelog.use: github-native, the release body is generated by GitHub and categorized via .github/release.yml and PR labels. Release footer links to full changelog.
• release.yml: Uses goreleaser/goreleaser-action with release --clean and contents: write permission.

Breaking changes and changelog

With github-native changelog, release-note sections are determined by PR labels and .github/release.yml, not by commit subject. Apply the breaking-change label to PRs that introduce breaking changes so they appear under "Breaking Changes" in the generated release notes. The commit subject convention (!:) is still recommended for semver and human readers (e.g. feat!: remove old API) but does not drive the release notes sections. Maintainers should apply the appropriate label (e.g. breaking-change, enhancement, bug) when merging so the next release is correctly categorized.

If the user only wants to understand the workflow, explain the steps and point to .goreleaser.yml, .github/release.yml, and .github/workflows/release.yml without running any commands.