Major version

As explained in API Design Patterns

A major version is the first component of a semantic version that indicates a backward-incompatible change.

A major version is the first number in a semantic version and signals a backward-incompatible API change. It helps users judge whether existing code should continue working. section 24.3.3

Renaming an API field

Renaming a field is typically backward incompatible, so an API might move from 1.0.0 to 2.0.0. Code written for major version N has no compatibility guarantee with major version M, even if it happens to work. section 24.3.3

Apply the major-version rule conservatively:

• Use the compatibility policy to decide whether a change is breaking; add a field under a compatible policy belongs in the minor version instead. section 24.3.3
• Treat soft deletion as potentially backward incompatible when its effects depend on data purpose, user expectations, privacy, security, or regulation. section 25.3.8

Figure 24.4 The different version numbers in a semantic version string

Use the semantic-version diagram to distinguish the major component from minor and patch components. section 24.3.3

How API Design Patterns covers it

How deep it goes

Defines the version component, contrasts it with minor versions, and applies it to field renaming and soft deletion.

Examples

Uses field renaming from 1.0.0 to 2.0.0 and adding a field from 1.0.0 to 1.1.0 as API examples.

What you can do after

Evaluate API changes and choose a major-version increment when compatibility is likely to break.

How it connects

Connects semantic versioning with backward compatibility, compatibility policy, minor versions, and soft deletion.

liveBookmanning.com

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

Also explained in

• 

  liveBookmanning.com
  PostgreSQL Mistakes and How to Avoid ThemA major release is a PostgreSQL release that introduces substantial features and may change internal system-table or data-file formats.

Compare how 2 books explain major version →

Related concepts

• semantic versioningpart of · Semantic Versioning is a version-numbering convention using MAJOR.MINOR.PATCH components to communicate compatibility impact: major for incompatible changes, minor for compatible additions, and patch for compatible fixes.
• breaking changeproduced by · A breaking change is a modification to an interface, behavior, format, configuration, or contract that can prevent existing consumers from working correctly without changes.
• versioningpart of · The practice of identifying and managing successive revisions of files, data, models, interfaces, or other artifacts so changes can be tracked and earlier states recovered.
• soft deletionconfigures · Soft deletion is a technique that marks or hides data as deleted while retaining its physical representation for recovery or later permanent removal.
• versionkind of · A version is a distinct, identifiable state or revision of an artifact, system, or product.

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.