# Release And Versioning

> Cuts a new release with semantic versioning and GoReleaser. Use when the user wants to release a new version, tag a release, or understand release workflow.

- Skill: `majiayu000/release-and-versioning` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/release-and-versioning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/release-and-versioning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/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](.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.