Semantic versioning

As explained in API Design Patterns

A semantic version string is a dotted three-number representation whose major, minor, and patch components communicate the nature of software changes.

Semantic versioning uses three dot-separated numbers to communicate the nature of API changes and compatibility expectations. section 24.3.3

Use the components to signal change impact:

• Increment the major version for backward-incompatible changes, such as renaming a field; code may not continue working across major versions. section 24.3.3
• Increment the minor version for backward-compatible functionality or behavior changes, such as adding a field under the compatibility policy. section 24.3.3

API field changes

Renaming a field can change version 1.0.0 to 2.0.0, while adding a field can change 1.0.0 to 1.1.0 when the compatibility policy treats the addition as backward compatible. section 24.3.3

Figure 24.4 The different version numbers in a semantic version string

Use the version-number diagram to distinguish the roles of the dotted components. section 24.3.3

How API Design Patterns covers it

How deep it goes

Defines three dotted numbers and explains major and minor semantics, while leaving patch behavior unspecified.

Examples

Uses field renaming and field addition to demonstrate incompatible and compatible API changes.

What it assumes

Assumes a defined compatibility policy for classifying API changes as backward compatible or incompatible.

What you can do after

Apply version increments to communicate whether API changes should preserve existing client behavior.

How it connects

Connects API versioning with backward compatibility and compatibility policy.

liveBookmanning.com

Read API Design Patterns on liveBook Get the book at manning.com

Also explained in

• 

  liveBookmanning.com
  Building Web APIs with ASP.NET CoreSemantic versioning is a version-numbering convention using MAJOR, MINOR, and PATCH components whose increments communicate compatibility and change significance.
• 

  liveBookmanning.com
  Go in Action, Second EditionSemantic versioning is a versioning convention in which changes to major, minor, and patch components communicate compatibility and release significance.
• 

  liveBookmanning.com
  The Design of Web APIs, Second EditionA semantic version number is a version identifier with major, minor, and patch components whose changes conventionally communicate compatibility impact.
• 

  liveBookmanning.com
  The Art of CodeSemantic versioning is a version-numbering convention in which major, minor, and patch components communicate compatibility and change significance.
• 

  liveBookmanning.com
  GitHub Actions in Action: Continuous integration and delivery for DevOpsSemantic versioning is a versioning scheme that communicates compatibility and change significance through major, minor, and patch version numbers.
• 

  liveBookmanning.com
  Infrastructure as Code, Patterns and Practices: With examples in Python and TerraformSemantic versioning is a version-numbering scheme in which major, minor, and patch components communicate the kinds of changes between releases.
• 

  liveBookmanning.com
  Terraform in Depth: Infrastructure as Code with Terraform and OpenTofuA semantic version is a version identifier following major, minor, and patch precedence rules.

Compare how 8 books explain semantic versioning →

Related concepts

• major versionhas part · A major version is the primary component of a version identifier that distinguishes a release line and commonly signals potentially backward-incompatible changes.
• FluentBitused by · Fluent Bit is a lightweight, open-source telemetry agent for collecting, processing, enriching, and forwarding logs and other event data.

This explainer was generated by Manning's knowledge graph from the text of API Design Patterns. The section links point to the parts of the book it draws on.