Skip to content

About

spec & reference implementation for modern semantic versions

Topics

Resources

Stars

8 stars

Watchers

0 watching

Forks

Repository files navigation

semver.xyz: Versions are a communication mechanism.

Specification · Libraries · Range selector · FAQ · History

Semantic Versions

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.

Libraries

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×

Where things live

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.

Layout

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

Develop

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 tables

The 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 bench

Each 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.

Deployment (Vercel)

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.

Registry

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.

License

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.

About

spec & reference implementation for modern semantic versions

Topics

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages