Skip to content
Package51 repository health

semver

A fast, spec-compliant Go library for parsing, comparing, and sorting semantic versions with npm-style range constraints.

Library Govv3.5.01,445 stars MIT License
go get github.com/Masterminds/semver/v3
View source

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Fair
  • Development activity16
  • Maintenance20
  • Community68
  • Maturity60
  • Momentum40

Technical analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation.How we score it →
Good
  • Architecture78
  • Code quality92
  • Innovation74
  • Learning curve65

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.

Used by 21 apps in this directory

Every app whose dependencies include github.com/Masterminds/semver/v3, nine to a page.

Showing 21 apps
Rust 66%Apache 2.0

agentgateway

6,340

AI Development · Developer Tools · Mcp

An open source AI-native proxy that secures, observes, and governs agent-to-LLM, agent-to-tool, and agent-to-agent communication through MCP, A2A, and unified LLM routing.

App
Built with
  • Rust 66%
  • Go 22%
Updated yesterdayView details
Go 61%Apache 2.0

Apache Answer

15,716

Community

Open-source Q&A platform for communities, help centers, and knowledge bases with AI assistant and plugin extensibility

App
Built with
  • Go 61%
  • TypeScript 36%
Updated 2 days agoView details
Go 56%Other

Cosmos-Server

6,204

Authentication · Security

All-in-one self-hosted home server with SmartShield anti-DDoS, Nebula mesh VPN, automatic HTTPS, and a 250-app marketplace — all secured behind a unified auth layer.

App
Built with
  • Go 56%
  • JavaScript 40%
Updated 1 weeks agoView details
Go 84%AGPL 3.0

Cozy Stack

1,267

File Storage · Productivity

Self-hosted personal cloud platform that unifies your files, apps, and devices in one private space you fully control.

App
Built with
  • Go 84%
  • TypeScript 10%
Updated yesterdayView details
Shell 49%MIT

Dokku

32,232

Devops · Hosting Control Panel

The smallest PaaS implementation you've ever seen — deploy apps via git push using Docker and Heroku buildpacks on your own server.

App
Built with
  • Shell 49%
  • Go 47%
Updated todayView details
Go 72%MIT

Gogs

47,962

Developer Tools

The painless self-hosted Git service that runs on anything from a Raspberry Pi to a $5 cloud droplet, delivering GitHub-like workflows as a single Go binary.

App
Built with
  • Go 72%
  • TypeScript 27%
Updated todayView details
TypeScript 47%AGPL 3.0

Grafana

78,021

Analytics · Monitoring

The open-source observability platform that unifies metrics, logs, and traces from any data source into dynamic, queryable dashboards.

App
Built with
  • TypeScript 47%
  • Go 47%
Updated todayView details
TypeScript 47%AGPL 3.0

Grafana

78,021

Analytics · Monitoring

The open-source observability platform that unifies metrics, logs, and traces from any data source into dynamic, queryable dashboards.

App
Built with
  • TypeScript 47%
  • Go 47%
Updated todayView details
Go 63%Apache 2.0

Harness Open Source

38,948

Code Editors · Developer Tools · Devops

A unified open source DevOps platform combining Git hosting, CI/CD pipelines, cloud development environments, and artifact registries in a single self-hosted system.

App
Built with
  • Go 63%
  • TypeScript 33%
Updated yesterdayView details

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers