liveBook · Manning

Semantic versioning

As explained in Microservices Patterns, Second Edition

Semantic versioning is a convention that assigns major, minor, and patch numbers to communicate the compatibility and nature of software changes.

Semantic versioning uses MAJOR.MINOR.PATCH numbers to signal the nature and compatibility of software changes: increment MAJOR for incompatible API changes, MINOR for backward-compatible enhancements, and PATCH for backward-compatible bug fixes. section 8.1.5

Originally intended for software packages, semantic versioning can also guide API evolution in distributed systems. Choose versioning practices with the change type and API style in mind. section 8.1.5

API versions can be communicated in different ways:

  • Put the major version at the start of a REST API URL path. section 8.1.5
  • Include the version in messages published by a messaging-based service. section 8.1.5

A three-part version

Spring Boot 3.5.6 illustrates the MAJOR.MINOR.PATCH format; the example is identified as current at the time of writing. section 8.1.5

How Microservices Patterns, Second Edition covers it

How deep it goes
Defines major, minor, and patch increments and shows where API versions can appear, without detailing a complete change process.
Examples
Illustrates the three-part format with Spring Boot 3.5.6 and describes URL-path and message-based API versioning.
What it assumes
Assumes API evolution concerns, including compatibility during rolling upgrades and messaging between old and new service versions.
What you can do after
Apply major, minor, and patch increments to communicate API compatibility and change type.
How it connects
Connects API versioning with backward compatibility, REST APIs, asynchronous messaging, and technology stacks.

Also explained in

Compare how 9 books explain semantic versioning →

Related concepts

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