Versioning
VER-zhun-ing
The practice of assigning unique version numbers to software releases to track changes over time.
Versioning means giving each release of your software a unique identifier so that users, developers, and systems can tell one release from another. When Stripe publishes version 2024-01-25 of their API, or React publishes version 18.2.0 of their library, that version number communicates something about what changed.
Good versioning is a communication tool. It tells consumers of your software what to expect. Did the API change in a way that will break their code? Is this a minor improvement or a major rewrite? Can they upgrade safely? The version number answers these questions before anyone reads the changelog.
For developer tools and APIs, versioning is especially critical. Your users build their software on top of yours. A surprise breaking change can cause their builds to fail, their apps to crash, and their trust in your product to evaporate. Clear, predictable versioning is a promise to your users that you respect their time and their code.
Examples
A library publishes a new version with breaking changes.
The team releases version 3.0.0 of their authentication SDK. The major version bump (2.x to 3.x) signals breaking changes. The changelog lists every API change, migration steps, and a compatibility guide. Users know they need to update their code. Those who are not ready can stay on 2.x, which will receive security patches for another year.
An API uses date-based versioning.
Stripe versions their API by date: 2024-01-25, 2024-06-20. Each version is a snapshot of the API at that date. New accounts get the latest version. Existing accounts stay on their current version until they explicitly upgrade. The API supports every version for years. This approach lets Stripe evolve the API without breaking any existing integration.
A team adopts versioning for their internal services.
Three internal teams depend on the user service API. Without versioning, every API change requires coordinating deploys across all three teams simultaneously. The team adds versioning: /v1/users and /v2/users can coexist. Each consumer team migrates on their own schedule. Deploys go from painful coordination exercises to routine releases.
In practice
Read more on the blog
Frequently asked questions
What is the difference between versioning and version control?
Versioning is about labeling releases (v1.0, v2.0). Version control is about tracking every change to source code over time (using Git, for example). You can have version control without versioning (many teams track every change but do not label releases) and versioning without version control (you could label releases without using Git). Most teams use both: Git for tracking code changes and semantic versions for labeling releases.
When should you bump a version number?
Every time you release changes to consumers. For libraries, that means every npm publish or package release. For APIs, that means every change that affects the contract with consumers. For internal tools, whenever you deploy changes that affect other teams. The key is consistency: consumers should be able to trust that a new version number means something changed, and the same version number always means the same code.
Related terms
A versioning scheme using MAJOR.MINOR.PATCH numbers to communicate the type of changes in each release.
A code change that causes existing functionality or integrations to stop working.
The ability of new software to work with older versions, data, or integrations without breaking them.
Application programming interface: a defined way for software programs to communicate with each other.
The process of releasing code to servers where users can access it.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.