| name | go-release |
| description | Manage the full Go module release lifecycle: determine next semver version, update CHANGELOG.md, create and push a git tag, and verify pkg.go.dev picks up the new version. Use when the user asks to tag a release, bump the version, update the changelog, or publish a new module version. |
Go Release
Tag a new semver release for the skeptic Go module. The release process
is lightweight — no GoReleaser, no binary uploads. The git tag is the
version, the CHANGELOG is the source of truth, and pkg.go.dev resolves
the rest.
When to use
- User asks to "release," "tag," "bump," or "publish" a new version
- A set of changes on
main is ready to be versioned
- pkg.go.dev needs to pick up a new module version
Semver rules for skeptic
| Bump | When |
|---|
| patch | Bug fixes, CI/CD changes, documentation, test improvements |
| minor | New rules, new features, new subcommands, license changes |
| major | Breaking CLI changes (renamed/removed flags, changed exit codes, removed subcommands) |
No major release has been made yet. Reserve v1.0.0 for when the CLI
surface is considered stable.
Version injection
skeptic does not embed a semver string via ldflags. The Makefile
injects buildCommit, buildDate, and buildGoVersion at build time.
The semver lives only in the git tag and CHANGELOG. No code changes are
needed for a tag to work.
Workflow
1. Determine the next version
git tag --sort=-v:refname | head -5
git log $(git describe --tags --abbrev=0)..HEAD --oneline
Review the commits since the last tag. Apply the semver rules above to
decide whether this is a patch, minor, or major bump.
2. Update CHANGELOG.md
Add a new section at the top of the changelog, below the # Changelog
heading and above the previous version entry:
## vX.Y.Z — YYYY-MM-DD
### Category
- Change description
Group changes under categories that match the nature of the work:
| Category | Use for |
|---|
| Detection | New rules, rule changes, behavior chains |
| Infrastructure | Scan engine, cache, decoders, correlation |
| CLI | New flags, subcommands, output changes |
| CI/CD | Workflow fixes, action updates |
| License | License changes |
| Documentation | Doc updates shipped with the release |
| Build | Toolchain, Makefile, build process |
Only include categories that have changes. Keep descriptions concise —
one line per change.
3. Commit the changelog
The changelog update must be committed to main before tagging. Since
main has branch protection, this goes through a PR:
git checkout -b release/vX.Y.Z-prep
git add CHANGELOG.md
git commit -m "Add vX.Y.Z changelog entry"
git push -u origin HEAD
gh pr create --title "Release vX.Y.Z" --body "Changelog entry for vX.Y.Z."
Merge the PR before proceeding to the tag step.
4. Tag the release
After the changelog PR is merged and main is up to date:
git checkout main
git pull origin main
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
Use an annotated tag (-a), not a lightweight tag. The message should
be the version string.
5. Verify pkg.go.dev
After pushing the tag, the Go module proxy needs to index the new
version. Trigger it and verify:
curl -s "https://proxy.golang.org/github.com/TGPSKI/skeptic/@v/vX.Y.Z.info"
Then check the pkg.go.dev page:
https://pkg.go.dev/github.com/TGPSKI/skeptic@vX.Y.Z
It may take a few minutes for pkg.go.dev to update. Verify that:
- The version appears in the versions list
- The license is detected correctly
- The module documentation renders
6. Optionally create a GitHub release
If the release warrants release notes beyond the changelog:
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file - <<'EOF'
Release notes here. Can reference the CHANGELOG for details.
EOF
For most releases, the changelog entry is sufficient and a GitHub
release is not required.
Guardrails
- Never tag on a dirty working tree.
git status must be clean.
- Never tag a commit that hasn't passed CI. Verify checks on
main
before tagging.
- Never force-push or delete a published tag. Once pushed, a tag is
immutable. If a mistake is found, create a new patch release.
- Never skip the changelog. Every tagged version must have a
corresponding CHANGELOG entry committed before the tag.
- Branch protection applies. Changelog commits go through PRs, not
direct pushes to
main. The tag itself can be pushed directly since
rulesets apply to branch refs, not tag refs.
Quick checklist
