Compatibility & Versioning
MuxMaster follows Semantic Versioning 2.0.0 and the Go module compatibility guidelines. This document is the contract between the project and its consumers.
Version scheme
v<MAJOR>.<MINOR>.<PATCH>[-prerelease]
| Bump | When | Examples |
|---|---|---|
| MAJOR | Backward-incompatible changes to a Tier 1 surface | Removing Mux.GET, changing its signature |
| MINOR | Backward-compatible additions; behavioural fixes that may be observable | New middleware, new option fields, performance improvements |
| PATCH | Bug fixes, security patches, internal refactors | Race fix, panic fix, doc-only updates |
Pre-release identifiers (-rc1, -beta1, -alpha1) signal that the version
is not yet covered by the SemVer guarantees below; downstream packagers
should pin exact pre-release versions.
Compatibility tiers
Every exported symbol falls into exactly one tier. The tier dictates the guarantee.
Tier 1 — Core Router (strongest guarantee)
The dispatch contract used by every consumer. Breaking changes require a MAJOR bump.
Mux,*Muxand its constructorNew()Mux.ServeHTTP(thehttp.Handlerimplementation)Mux.Handle,Mux.HandleFunc,Mux.HandleE,Mux.HandleFast- All method shortcuts:
GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS,CONNECT,TRACE,QUERYand their*Eand*Fastvariants (every method has a*Fastvariant on*Mux; there is noCONNECTEorTRACEE) Mux.Use,Mux.UseFast,Mux.PreMux.Group,Mux.Route,Mux.With,Mux.Mount,Mux.ServeFiles,Mux.Match,Mux.ANYGroupand all of its methodsParams,Param,Params.Get,Params.Lookup,Params.Mapand the typed accessorsInt/Int64/Uint64/Float64/BoolPathParam,ParamsFromContext,RoutePatternHandlerFuncE,HTTPError,ErrorFastHandler,FastMiddleware- Public
Muxstruct fields documented in the README options section:RedirectTrailingSlash,RedirectFixedPath,HandleMethodNotAllowed,HandleOPTIONS,CaseInsensitive,UseRawPath,UnescapePathValues,RedirectCode,NotFound,MethodNotAllowed,GlobalOPTIONS,PanicHandler,ErrorHandler
Tier 2 — Middleware sub-package
github.com/FlavioCFOliveira/MuxMaster/middleware. Each middleware is
documented as a constructor function and its options struct.
Breaking changes to a middleware constructor or its Options struct
require a MAJOR bump. Adding new fields to an Options struct is a MINOR
change — consumers using struct literals without field names will break,
but the recommended idiom is named fields, which is unaffected.
Tier 3 — Introspection / Debug
Mux.Lookup, Mux.Routes, Mux.Walk, Mux.WalkFast, RouteInfo,
Mux.Rebuild. Used by tooling and tests. Breaking changes are signalled
in the CHANGELOG ### Changed section and require a MINOR bump (Tier 3
is intentionally less rigid than Tier 1 to allow telemetry and tooling
evolution).
Tier 4 — Internal (no guarantee)
Symbols exported because Go has no other visibility scope but documented
as "internal" in their GoDoc, plus everything under
internal/, competitor/, reports/ and examples/. May change at any
time without notice.
Deprecation policy
- A symbol that will be removed is first marked deprecated with a
// Deprecated: <reason>. Use <replacement> instead.comment in GoDoc. - The deprecation is announced in the CHANGELOG
### Deprecatedsection. - The deprecated symbol must remain functional for at least one MINOR release. Removing it is then a MAJOR change.
- CI runs
staticcheck(which includes SA1019, use of deprecated symbols) on the root module. Theexamples/directories are separate modules that CI does not check; contributors runstaticcheckin an example they change (see CONTRIBUTING.md).
Example timeline:
v1.4.0 — Mark Foo as // Deprecated: use Bar.
v1.5.0 — Foo still works. Bar is the documented path.
v2.0.0 — Foo removed.
Breaking change detection (CI)
Every pull request runs apidiff
on the root package against the most recent tagged release. Detected
incompatible changes fail the build unless the pull request carries the
api-break label. The middleware package is not covered by this check;
changes to it are reviewed against api.md, which CI requires to be
regenerated (make api) whenever an exported symbol or its doc comment
changes.
Go version policy
go.mod declares the minimum supported Go version. Bumping it is a
MINOR change, not a MAJOR one — consistent with the
Go core team's published guidance.
The CI matrix tests against the declared minimum (Go 1.27.1) and against
stable on Linux, macOS and Windows, plus Linux/arm64; a non-blocking
canary job also builds and tests the root package with Go tip.
Stability of behaviour, not just types
This project considers the following non-type properties as part of the public contract:
- HTTP status codes returned by built-in handlers (404 NotFound, 405 MethodNotAllowed, etc.)
- Header semantics (
Allow,WWW-Authenticate,Vary: Origin,Content-Typedefaults) - Order in which middlewares execute relative to dispatch (
Prebefore tree lookup,Useafter) - Error sentinel identity (e.g.
errors.Is(err, ErrParamNotFound)if it becomes exported)
Behavioural breaks are subject to the same MAJOR/MINOR rules as type
breaks. They will be enumerated in the CHANGELOG ### Changed section
with a brief migration note.
Security patches
Only the latest release receives security fixes. They are released as PATCH versions and announced via GitHub Security Advisories. The supported versions and the reporting policy are on the Security page.
Glossary
The terms below appear throughout this page and the wider documentation; their meanings are pinned here so cross-page references are unambiguous.
- API
- The set of exported types, functions, methods, and constants that consumers may rely on. Membership is defined per tier above.
- MAJOR version
- The first number in a
vX.Y.Ztag. Incrementing it signals a backward-incompatible change to the Tier 1 surface. - MINOR version
- The second number in a
vX.Y.Ztag. Incrementing it signals a backward-compatible addition or a behavioural fix that may be observable. - PATCH version
- The third number in a
vX.Y.Ztag. Incrementing it signals a bug fix, security patch, or internal refactor with no API impact. - Pre-release identifier
- A suffix such as
-rc1,-beta1, or-alpha1on a version tag, indicating the version is not yet covered by the SemVer guarantees above. Pin pre-release versions exactly when packaging.
Questions
Open an issue on github.com/FlavioCFOliveira/MuxMaster if you find an undocumented behaviour you depend on; we will either formalise it as part of the public contract or document it as Tier 4.