Specification · Libraries · Range selector · FAQ · History
An open specification for how version numbers are assigned, incremented, grouped, compared and matched: a spiritual successor to Semantic Versioning 2.0.0-rc.1 that restores build precedence and formally defines sets, ranges, comparators and channels.
The specification lives in spec/SPEC.md. This repository also
holds its extensions, the conformance suite, the reference implementation and
its ports, and the semver.xyz site.
Every implementation passes the same conformance suite and is benchmarked against the libraries it replaces.
| Language | Package | Conformance | Compared with | Speed vs. it |
|---|---|---|---|---|
| JavaScript | semantic-versions (npm) |
476/476 | semver 396/476 |
2.4–11× |
| Rust | semantic-versions (crates.io) |
476/476 | nodejs-semver 366/476 |
0.9–1.3× |
| Python | semantic-versions (PyPI) |
476/476 | node-semver 366/476 |
1.5–17× |
| Go | semver.xyz/go (pkg.go.dev) |
476/476 | Masterminds/semver 348/436 |
2.8–23× |
| Ruby | semantic-versions (RubyGems) |
476/476 | semantic_range 366/476 |
1.7–20× |
| Java | xyz.semver:semantic-versions (Maven Central) |
476/476 | semver4j 356/436 |
9.2–26× |
| .NET | SemanticVersions (NuGet) |
476/476 | Semver 365/436 |
1.3–10× |
| PHP | vltpkg/semantic-versions (Packagist) |
476/476 | composer/semver 282/436 |
1.0–3.7× |
Each document has exactly one source; the site renders or links to it rather than keeping a second copy.
| What | Source of truth | On the site |
|---|---|---|
| The specification | spec/SPEC.md |
/spec/, rendered from the Markdown at build time |
| Extensions | extensions/*/*.md |
/extensions/, one presentation page each |
| FAQ | site/src/app/faq/page.tsx |
/faq/ |
| Comparison with SemVer 2.0.0 | site/src/app/proposal/page.tsx |
/proposal/#compare |
| BNF grammars | site/public/spec/*.bnf |
/grammar/ |
| Conformance cases | conformance/*.json |
run by every implementation's test suite |
| Implementations (for the page and READMEs) | benchmarks/languages.mjs |
/libraries/ |
| Benchmark results | benchmarks/results/*.json |
/libraries/ and every package README, rendered from the JSON |
To change the specification, edit spec/SPEC.md and nothing else: it reads
correctly on GitHub, and vlt run dev -w site live-reloads /spec/ as you
save. Keep headings plain where other pages link to them (#context,
#precedence, #pre-release-channels, #build-channels), since heading ids
follow GitHub's slug rules on both GitHub and the site.
This repository is a vlt workspace (vlt.json):
.
├── spec/
│ └── SPEC.md # The specification (canonical)
├── conformance/ # Language-neutral test cases (JSON) for any implementation
├── extensions/ # Extension specifications (markdown + source)
│ ├── variants/ # 1. Build Variants: which artifact
│ ├── integrity/ # 2. Package Integrity: which bytes
│ └── dependency-locks/ # 3. Dependency Locks: which graph (builds on 1 and 2)
├── libraries/ # One directory per language, all passing conformance/:
│ ├── javascript/ # npm `semantic-versions` (the reference implementation)
│ ├── rust/ # crates.io `semantic-versions`
│ ├── python/ # PyPI `semantic-versions`
│ ├── go/ # module `semver.xyz/go`
│ ├── ruby/ # RubyGems `semantic-versions`
│ ├── java/ # Maven Central `xyz.semver:semantic-versions`
│ ├── dotnet/ # NuGet `SemanticVersions`
│ └── php/ # Packagist `vltpkg/semantic-versions`
├── benchmarks/ # Real-world corpus, results, and the shared table renderer
├── assets/ # README banner (and the script that draws it)
└── site/ # The semver.xyz site (Next.js, deployed on Vercel)
├── next.config.ts # Trailing-slash URLs, /tools redirects, @affordances/md
├── vercel.json # Installs vlt, then `vlt run build -w site`
├── public/ # favicon, fonts, downloadable *.bnf grammars
└── src/
├── app/ # One folder per page (page.tsx), plus the text routes
│ ├── page.tsx # Home
│ ├── spec/ # Page shell; content rendered from spec/SPEC.md
│ ├── extensions/ # One page per extension, in layering order
│ ├── grammar/ # BNF grammars + downloads
│ ├── selector/ # Client-side range selector (uses the parser)
│ ├── proposal/ # Semantic Versioning 3.0.0 proposal + 2.0.0 comparison
│ ├── origin/ # A short history of Semantic Versioning
│ ├── faq/ # Frequently asked questions
│ ├── libraries/ # Libraries in every language, benchmarks and conformance tables
│ ├── license/
│ ├── agents/ # For agents: llms.txt, Markdown twins, the graph, MCP
│ ├── */state.ts, */actions.ts # Each page's Affordances graph: what it shows, what can be done
│ ├── llms.txt/, llms-full.txt/, sitemap.xml/, robots.txt/, spec/SPEC.md/, …
│ │ # Route handlers for the machine-readable files, built from the Markdown
│ ├── api/affordances/ # The graph (@affordances/next) and every page as Markdown (@affordances/md)
│ └── globals.css # The design system
├── components/ # Nav, footer, theme, the pages' interactive parts
└── lib/ # Spec renderer, corpus (llms.txt), benchmarks, bundled sources, DOM modules
Install vlt (curl -fsSL https://install.vlt.sh | bash,
Node 22.22 or newer), then:
vlt install
vlt run dev -w site # start the site (Next.js) at http://localhost:3000
vlt run build -w site # production build into site/.next
vlt run start -w site # serve the production build
vlt run test -w libraries/javascript # run the parser test suite (tap), incl. conformance
vlt run bench -w libraries/javascript # benchmark against node-semver and @vltpkg/semver, refresh the tablesThe other implementations live outside the vlt workspace and use their own toolchains; each README has the details:
cd libraries/rust && cargo test && cargo bench --bench compare
cd libraries/python && python -m unittest discover -s tests && python bench/compare.py
cd libraries/go && go test ./... && (cd bench && go run .)
cd libraries/ruby && bundle exec rake test && bundle exec rake bench
cd libraries/java && javac -d build $(find src -name '*.java') && java -cp build xyz.semver.ConformanceTest && bench/run.sh
cd libraries/dotnet && dotnet run --project tests/SemanticVersions.Conformance && dotnet run -c Release --project bench
cd libraries/php && composer install && composer test && composer benchEach benchmark writes benchmarks/results/<language>.json. Afterwards,
node benchmarks/report.mjs refreshes the tables in every README; the site
renders the same results files at build time. To add a language, add it to
benchmarks/languages.mjs.
The root package.json also exposes convenience wrappers, e.g. vlt run build.
The machine-readable files served from the site root (/llms.txt,
/llms-full.txt, /sitemap.xml, /robots.txt and the Markdown mirrors of
the spec and extensions) are route handlers under site/src/app, built from
the canonical Markdown, which site/src/lib/sources.ts bundles into the site;
site/src/lib/corpus.ts lists what goes where.
The site runs on Affordances. Every page is
served as Markdown by @affordances/md (add .md to its path, /faq.md, or
request it with Accept: text/markdown), and answers with a graph when asked
with Accept: application/vnd.affordances+json: each page's state.ts says
what it shows, and its actions.ts what an agent can do there. The range
selector's actions (select, desugar, parse, compare, bump) run the
reference parser, the spec's readSection returns one section, and the
grammars' readGrammar returns a BNF; all are public and read-only.
/.well-known/affordances.json is the site index, /mcp is the site as an
MCP server (streamable HTTP, the same two tools as npx @affordances/mcp),
and /agents/ explains it to agents. Every
document page carries a Copy page / Open in menu (site/src/components/page-actions.tsx,
built on @affordances/md/react/client) that copies the page's Markdown twin
or opens it in Claude, ChatGPT or Claude Code. @affordances/next regenerates site/.affordances/manifest.ts
(gitignored) from those files on every build.
The range selector imports the semantic-versions
parser directly, so the site and the reference implementation never drift.
The site is a Vercel project with its root directory set
to site/, served at semver.xyz. Every push to main
deploys production and every pull request gets a preview, through Vercel's Git
integration; there is no deploy workflow in this repository.
site/vercel.json installs vlt on the build machine and
runs vlt run build -w site, so Vercel builds with the same lockfile as CI.
The build reads spec/SPEC.md, the extension Markdown and
benchmarks/results/*.json from the repository root, which is why the
project's root directory is site/ and not a copy of it.
vlt.json pins the registry aliases under its config key: npm
to https://registry.npmjs.org/, so vlt-lock.json resolves from the public
registry for everyone (CI included) rather than from whatever registry a
contributor's user-level vlt config points at, and main to vlt's registry,
because vlt writes every alias it knows into the lockfile's options and a
frozen install fails when they differ (vltpkg/vltpkg#2208).
Pinning both means a lockfile written on a machine with a user-level main
alias is the lockfile CI and Vercel expect.
The specification and extension texts are licensed under
CC BY 3.0. The code (every library
under libraries/, the benchmarks and the site) is licensed under the
Apache License 2.0.
Releasing a library: see .github/RELEASING.md.