[GH-ISSUE #681] proposal: LIBRARY version #2199

New Issue

GiteaMirror · 2026-04-20T10:11:55-05:00

GiteaMirror commented

2026-04-20 10:11:55 -05:00

Originally created by @coldnebo on GitHub (Mar 26, 2021).
Original GitHub issue: https://github.com/semver/semver/issues/681

While looking at Rails versioning, I notice that some PATCH level changes have breaking changes now. For example:

Update Changelog entry for 5.2.4.1 to warn of breaking changes

SemVer 2.0 says:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API

If Rails followed this advice, then the logical semver increment from 5.2.4 would have to be 6.x, not 5.2.4.1. But Rails 6.x already means something bigger than an incompatible API change -- it means a group of incompatible architectural changes with the previous version.

Indeed, many gems in the ecosystem face this dilemma.

Proposal: LIBRARY version

Given a version number LIBRARY.MAJOR.MINOR.PATCH, increment the:

LIBRARY version when you make incompatible architectural changes.
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.

So, for the above example, the bump could have been: 5.3.0.0

Originally created by @coldnebo on GitHub (Mar 26, 2021). Original GitHub issue: https://github.com/semver/semver/issues/681 While looking at Rails versioning, I notice that some PATCH level changes have breaking changes now. For example: * [Update Changelog entry for 5.2.4.1 to warn of breaking changes](https://github.com/rails/rails/commit/c1ca9c7b365cdac9ccd8eb1716173ea3aef89892) SemVer 2.0 says: > 8. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API If Rails followed this advice, then the logical semver increment from 5.2.4 would have to be 6.x, not 5.2.4.1. But Rails 6.x already means something bigger than an incompatible API change -- it means a group of incompatible architectural changes with the previous version. Indeed, many gems in the ecosystem face this dilemma. ## Proposal: LIBRARY version Given a version number LIBRARY.MAJOR.MINOR.PATCH, increment the: LIBRARY version when you make incompatible architectural changes. MAJOR version when you make incompatible API changes, MINOR version when you add functionality in a backwards compatible manner, and PATCH version when you make backwards compatible bug fixes. So, for the above example, the bump could have been: 5.3.0.0

GiteaMirror closed this issue

2026-04-20 10:11:56 -05:00

GiteaMirror commented

2026-04-20 10:11:58 -05:00

@coldnebo commented on GitHub (Mar 26, 2021):

ah, sorry, I'll circle back with an RFC for this.

@coldnebo commented on GitHub (Mar 26, 2021): ah, sorry, I'll circle back with an RFC for this.

GiteaMirror commented

2026-04-20 10:11:59 -05:00

@ljharb commented on GitHub (Mar 26, 2021):

Rails doesn’t follow semver.

@ljharb commented on GitHub (Mar 26, 2021): Rails doesn’t follow semver.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#2199