versioning

Versioning is the practice of assigning unique identifiers to the successive states or releases of an artifact, such as software, APIs, data models, or documents. Version numbers provide a historical record of changes, enable reproducibility, and support compatibility management by signaling the level of change and its potential impact on consumers.

The most common schemes include semantic versioning, which uses three numeric components, and calendar versioning, which uses dates. Semantic versioning specifies MAJOR.MINOR.PATCH. Increments follow rules: MAJOR for incompatible API changes, MINOR for new functionality that remains backward compatible, and PATCH for backward-compatible bug fixes. Pre-release versions (e.g., 2.1.0-alpha.1) and build metadata (e.g., 2.1.0+20130313144700) convey additional information.

Calendar versioning assigns versions based on release date, such as year.month or year.month.day, emphasizing recency over compatibility guarantees. Other schemes may incorporate version stubs, iteration counts, or branch names. Organizations choose schemes to balance clarity, stability, and automation.

Versioning is commonly used with version control systems by tagging releases. A clear version policy, changelogs, and immutable release artifacts improve traceability and reproducibility. Effective versioning supports dependency management, rollback, and user communication, reducing the risk of mismatched expectations between producers and consumers.

In practice, versioning spans software, libraries, APIs, data formats, and standards. Adopting a consistent scheme, documenting rules, and aligning with downstream ecosystems are core principles. The goal is to convey change intent and compatibility so users can decide when and how to upgrade.