liveBook · Manning

Versioning

As explained in The Art of Code

Versioning is the practice of identifying successive revisions of an interface or artifact so clients can distinguish and manage compatibility between them.

Version control identifies successive interface revisions so clients can distinguish compatibility changes. For public APIs, the goal is not merely labeling releases but preserving trust while systems evolve. section 9.4.2

Use a predictable compatibility policy:

  • Apply semantic versioning: MAJOR signals breaking changes, MINOR adds backward-compatible capabilities, and PATCH fixes bugs. section 9.4.2
  • Keep older methods available while clients plan migration, and mark them deprecated with a clear replacement. section 9.4.2
  • Prefer adding changes alongside an existing interface; smaller evolutions can use optional parameters that older clients ignore. section 9.4.2

Make removal visible

A Java method can be marked @Deprecated(since = "2.1", forRemoval = true), allowing tooling and developers to recognize planned removal before the interface disappears.

How The Art of Code covers it

How deep it goes
Explains semantic-version meanings, deprecation, compatibility risks, and method extension, but does not detail repository workflows.
Examples
Uses changed fields, validation rules, endpoint URLs, optional parameters, and a Java deprecation annotation as compatibility examples.
What it assumes
Assumes familiarity with public APIs and dependent clients while demonstrating compatibility concerns through concrete interface changes.
What you can do after
Apply it via semantic versioning and deprecation practices when evolving a public interface.
How it connects
Connects versioning with API design, backward compatibility, deprecation, migration, and semantic versioning.

Also explained in

Compare how 25 books explain versioning →

Related concepts

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