Versioning

Kind: mechanism

Layer: Contracts Core

Record: architecture:versioning

Severity: mandatory

Scope: API, schema, package, service

Canonical: Ontology

A mechanism that labels each release of an interface or schema, so consumers can tell compatible changes from breaking ones.

Listed in Architecture principles, after Forward Compatibility and before Protocol Compatibility.

Requires

• Stable Interfaces
• Compatibility Policy

Reinforces

• Backward Compatibility
• Governance

Enables

• Controlled Evolution

Conflicts with

• Silent Breaking Changes

In tension with

• Version Sprawl

Tensions

• Versioning / Version Sprawl

Contracts

• Versioned Evolution Over Breaking Change
• Living Profile Kernel

Violated by

• Unversioned Breaking Change

Severity

• mandatory

Category

• Contracts / Interfaces / Compatibility

Refactors

• Schema Drift
• Cyclic Deployment Dependency
• Cache Poisoning by Design
• API Contract
• Service Contract
• Canonical Schema

Required by

• API Contract
• Protocol Compatibility
• Integration Events

Linked from

• Seven controls, seven classes
• Anti-patterns
• Contracts / Interfaces / Compatibility
• Event / Messaging / Asynchronous Architecture
• Schema / Canonical Data / Semantics
• Security / Privacy / Compliance / Governance
• Contracts / Interfaces / Compatibility
• Core Vocabulary
• Architectural Rules
• Living profile
• Severity levels
• The resolutions