semver

Masterminds/semver is a pure Go package for working with Semantic Versions: parsing version strings, sorting them, and checking whether they satisfy a constraint expression. It supports both strict RFC-compliant parsing via StrictNewVersion and a coercive NewVersion that tolerates partial or non-compliant version strings (like CalVer-style values with leading zeros), making it useful for real-world version strings that don’t perfectly follow the spec.

Constraint checking follows the range conventions popularized by npm and Cargo rather than a from-scratch design, supporting comparison operators (=, !=, >, <, >=, <=), hyphen ranges, wildcards (x, X, *), and the tilde (~) and caret (^) shorthand operators for patch- and major-level ranges. The library is widely used as the versioning engine inside dependency-management and package-manager tooling across the Go ecosystem, including Helm and dep.

What You Get

• A Version type with strict (StrictNewVersion) and coercive (NewVersion) parsing
• A Constraints type supporting =, !=, >, <, >=, <=, hyphen ranges, wildcards, ~, and ^ operators
• A Collection type implementing sort.Interface for sorting slices of versions
• JSON, text, and database/sql (Scan/Value) marshaling support on Version
• Safe increment helpers (IncMajorE, IncMinorE, IncPatchE) that return errors on uint64 overflow instead of panicking

Common Use Cases

• Validating that a dependency’s installed version satisfies a version range declared in a manifest file
• Sorting a list of Git tags or release versions into semantic order
• Implementing update-policy logic (e.g. “only auto-upgrade patch releases”) using tilde/caret constraints
• Storing and retrieving parsed version values directly from a SQL database column

Under The Hood

Architecture

The package is a single flat semver package with no internal layering: version.go defines the Version type and its parsing/comparison/marshaling methods, constraints.go defines Constraints/constraint and the regex-driven range grammar (rewriteRange, findConstraintRegex, validConstraintRegex), and collection.go is a small adapter implementing sort.Interface. There is no dependency injection or multi-layer design because the surface area is intentionally narrow: parse a string into a Version, evaluate a Constraints against it. Data flows one direction — string in, typed struct out, boolean/int out of comparisons — with no external I/O and no state beyond two package-level regexes compiled once in init(). Because the type is small and consumers only ever touch exported methods, changes to the core struct stay contained to this one file.

Tech Stack

go.mod declares the module for Go 1.21 with zero third-party dependencies — the implementation relies solely on the standard library (regexp, strings, strconv, encoding/json, database/sql/driver). Build tooling is a plain Makefile wrapping go test/go vet, CI runs through GitHub Actions (test, golangci-lint, CodeQL, and a native Go fuzz job) against current Go releases, and golangci-lint v2 is configured with a strict linter set including gosec, gocyclo, errcheck, staticcheck, revive, and unparam. As a dependency-free leaf library it’s built to be vendored into other Go binaries — notably Helm and dep — and it implements database/sql/driver.Valuer/Scanner purely so consuming applications can persist Version values without extra glue code.

Code Quality

Testing is extensive: version_test.go and constraints_test.go each carry roughly 1,200 lines of table-driven tests covering parsing edge cases, comparison ordering, and marshaling, alongside a dedicated benchmark suite and a CI fuzz job exercising the parser continuously. Error handling is idiomatic Go — exported sentinel errors (ErrInvalidSemVer, ErrEmptyString, ErrIncrementOverflow) are returned rather than panicking, and ...E-suffixed increment variants were added specifically to replace silent-overflow behavior with explicit, wrappable errors. Naming is consistent and idiomatic, the codebase is gofmt/goimports-formatted, and CI enforces a strict golangci-lint v2 profile plus CodeQL static analysis. Bounded-input constants (MaxVersionLen, MaxConstraintLen, MaxConstraintGroups) show deliberate hardening against oversized or adversarial input.

API Design The public API is deliberately minimal: NewVersion offers permissive coercion while StrictNewVersion enforces spec compliance, letting callers opt into exactly the leniency they need, and MustParse gives a panic-on-error convenience for tests and constants. Constraint syntax intentionally mirrors what developers already know from npm and Cargo (~, ^, hyphen ranges, wildcards) instead of inventing new range grammar, lowering the learning curve for anyone coming from another ecosystem’s version ranges. Zero-boilerplate integration is a deliberate goal — Version implements fmt.Stringer, JSON, text, and SQL driver interfaces so it drops directly into JSON APIs, config structs, and database columns without adapter code, and package-level toggles (CoerceNewVersion, DetailedNewVersionErrors) let callers tune strictness and performance trade-offs globally.