Releasing
ezz is distributed as a private Go module. There is no registry to publish to and no build step — a release is a Git tag, and consuming services resolve it by tag name. That makes releasing cheap, and it also means an untagged change is invisible to everyone downstream.
Write commits the release notes can read
Release notes are generated by changelogithub, which reads Conventional Commits. The format is the subject line:
type(scope): description
| Prefix | Section in the notes |
|---|---|
fix: | 🐞 Bug Fixes |
feat: | 🚀 Features |
perf: | 🏎 Performance |
refactor:, chore:, docs:, test: | Grouped under their own headings |
Any type with !, e.g. feat!: | 🚨 Breaking Changes, listed first |
The scope is optional and reads well as the package: feat(auth): add passkey provider, fix(binding): reject empty content-type.
!; nothing else infers them, and the major-version decision below depends on spotting them.Releasing
There is nothing to run. Push to main and .github/workflows/release.yml does the rest:
It only starts for Go changes
The workflow is filtered to **.go, go.mod, and go.sum. A push that touches only documentation, the docs site, the Makefile, or the workflow itself does not start a run at all — nothing appears in the Actions tab, because only these paths can change what a consuming service downloads. go.mod and go.sum are in the list because a dependency bump is consumer-visible without touching a single .go file.
Commits from a filtered-out push are not lost. The version is computed from every commit since the last tag, not from the commits in one push, so a feat: that only edited markdown is still counted by the next run that does touch Go — and correctly makes it a minor bump.
It picks the version
The commits since the last tag decide the bump. A feat: makes it a minor, a fix:, perf:, or refactor: makes it a patch, and the highest one present wins.
If the push contains none of those — only docs:, chore:, test:, ci:, or unformatted subjects — nothing is released and the run stops. Comment tweaks do not burn version numbers.
It verifies before tagging
go mod tidy leaves no diff, go vet, and go test -race ./... — which covers both examples, since neither is a separate module. Only then is the tag created and pushed.
It proves the tag is consumable
A throwaway module outside the repository resolves the new tag and imports every documented path. This is the only check that exercises the real consumer path — proxy bypass, Git authentication, tag resolution, and module zip contents. Building inside the ezz repository proves none of it, because a local checkout satisfies every import regardless of what the tag contains.
If this fails, the tag is deleted again and no release is published. Consumers fetch direct from GitHub with no proxy cache, so removing the ref genuinely retracts the version.
It writes the notes
changelogithub groups the commits and creates the GitHub release. Preview what it will say before you push:
pnpx changelogithub@0.13 --dry --from v1.1.0 --to HEAD
go mod tidy in the throwaway module. When an import is not satisfied by the tag under test, tidy does not fail — it quietly upgrades to a newer tag that does satisfy it, and you get a passing smoke test for a broken release. The workflow asserts the resolved version never moved off the tag, which is the only reason its check means anything.Forcing a specific version
Automatic bumps never go major, for a reason covered below. To release an exact version — a v2.0.0 after changing the module path, or a rebuild of a version the planner would skip — trigger the workflow by hand:
gh workflow run release.yml -f version=v2.0.0
The version you pass is used verbatim. Every verification gate still runs, so a v2.0.0 whose go.mod still says module github.com/sulv-io/ezz fails at the consume step and the tag is rolled back.
.go file — a corrected go:generate directive in a comment, say, or a fixture the tests depend on.When to bump major
Go enforces semantic versioning through the import path, and it does so only at the major version. Within v1, go get -u will happily move a service from v1.1.0 to v1.9.0, so anything that breaks a caller has to be either avoided or promoted to v2.
| Change | Version |
|---|---|
| New route helper, new middleware, new optional field | Minor |
| Bug fix with no signature change | Patch |
| Renamed or removed exported identifier | Major |
| Changed function signature or interface method set | Major |
| Package moved to a different import path | Major |
v2 and above as a distinct module: the path in go.mod becomes github.com/sulv-io/ezz/v2, every internal import has to be updated to match, and every consuming service rewrites its imports too. The suffix is permanent. Given that ezz has a small and known set of consumers, absorbing a breaking change as a minor bump and updating those services directly is usually the cheaper trade — but it is a deliberate choice, not an accident.This is why the workflow never bumps major on its own. A feat!: commit is released as a minor, with a note on the run summary saying so. Tagging v2.0.0 while go.mod still reads module github.com/sulv-io/ezz produces a tag Go flatly refuses to resolve — major version must be compatible: should be v0 or v1, not v2 — so an automatic major bump would publish a version nobody can install. Going major means editing go.mod and every import first, then triggering the release by hand.
That trade is what produced the current numbering. The rewrite that moved the framework from core/ to the module root was breaking by any reading of semver, and it shipped as v1.1.0 rather than v2.0.0 because the alternative was a permanent /v2 in every import path to protect consumers that did not exist. The cost is that v1.0.0 is still resolvable and still broken — see Installation.
What ships to consumers
The module zip is built from the repository tree, not from a manifest, so anything committed at the tagged commit is downloaded by every consuming service. Two things keep that small:
- Test-only dependencies are pruned.
miniredisis a direct requirement ingo.mod, but Go's module graph pruning keeps test-only dependencies of a dependency out of the consumer's graph, so it never appears in a consuming service'sgo.mod. - Test files are included but not built.
_test.gofiles ship in the zip and are ignored unless someone runs tests against the module directly.
Everything else in the tree — documentation, fixtures, the docs site — is downloaded. It is currently around 157 KB, which is not worth optimizing, but it is worth not committing binaries or vendored dependencies into.
.gitignore. If you add a new example that produces one, add its output path there too rather than relying on the name being caught.