[PR #399] [CLOSED] Proposal for 2.1: Explicitly declare forward- and backward-compatibility #4107

New Issue

GiteaMirror · 2026-06-08T20:29:19-05:00

GiteaMirror commented

2026-06-08 20:29:19 -05:00

📋 Pull Request Information

Original PR: https://github.com/semver/semver/pull/399
Author: @ghost
Created: 10/12/2017
Status: ❌ Closed

Base: master ← Head: master

📝 Commits (4)

55dad9b Outline SemVer 2.1
08293b1 Delete semver.svg
fc46735 Add Code Highlighting
1f687ba Fix Typos

📊 Changes

2 files changed (+200 additions, -984 deletions)

View changed files

📝 semver.md (+200 -156)
➖ semver.svg (+0 -828)

📄 Description

Taken from the proposed changes:

Don't be fooled by the new version number; while backward-compatible (of course), version 2.1 fundamentally changes the way SemVer works. It is recommended that you read this documentation thoroughly.

In short, 2.1 lets you safely use more versions of your dependancies than 2.0.0 would, without breaking any code. Its implementation is the purest form of knowing exactly which versions can act as complete substitutes for any other version. 2.0.0 doesn't quite allow for this, because its hard cap at 3 places of version precision inherently loses information about forward and backward compatibility as more and more minor-level changes are added. As you will see, SemVer 2.1 improves upon this model by explicitly declaring forward- and backward-compatibility with any other version in an easy-to-understand way.

Given a hypothetical version 1.2.3:

If making changes that are both forward- and backward-compatible with the current version (i.e. a bug fix), add .1 to the far right of the version number. In this case: 1.2.3.1.
If making changes that are backward-compatible but not forward-compatible with the current version (i.e. an addition to the API), increment the version number. In this case: 1.2.4.
If making changes that are not backward-compatible with the current version (i.e. an API removal), increment the shortest part of the version number for which the changes are not backwards compatible, and drop the rest.
- In this case, assuming the change is backwards-compatible with version 1 (but not version 1.2): 1.3.
- Alternately, assuming the change isn't backward-compatible with any prior version: 2.

So, for example, if you used you used version 1.2 of our hypothetical piece of software in your code, you know that any version beginning with "1.2" will function fully as a drop-in replacement. So, in the above examples, 1.2.3, 1.2.3.1 and 1.2.4 will work, but 1.3 and 2 won't. However, the true
beauty of SemVer 2.1 lies in its granularity: because version numbers can be of arbitrary length, you are able to know exactly which versions are compatible with (theoretically infinite) precision.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/semver/semver/pull/399 **Author:** [@ghost](https://github.com/ghost) **Created:** 10/12/2017 **Status:** ❌ Closed **Base:** `master` ← **Head:** `master` --- ### 📝 Commits (4) - [`55dad9b`](https://github.com/semver/semver/commit/55dad9b6252101be52e943e8495446cf73db24c4) Outline SemVer 2.1 - [`08293b1`](https://github.com/semver/semver/commit/08293b10a3cfb19367264541eda7731b6f24d96b) Delete semver.svg - [`fc46735`](https://github.com/semver/semver/commit/fc46735139a022530e8445b0748b35ca819402c5) Add Code Highlighting - [`1f687ba`](https://github.com/semver/semver/commit/1f687ba989d0e4638d50c2016c031f6561c6603e) Fix Typos ### 📊 Changes **2 files changed** (+200 additions, -984 deletions) <details> <summary>View changed files</summary> 📝 `semver.md` (+200 -156) ➖ `semver.svg` (+0 -828) </details> ### 📄 Description ## Taken from the proposed changes: Don't be fooled by the new version number; while backward-compatible (of course), version `2.1` fundamentally changes the way SemVer works. It is recommended that you read this documentation thoroughly. In short, `2.1` lets you safely use more versions of your dependancies than `2.0.0` would, without breaking any code. Its implementation is the purest form of knowing exactly which versions can act as complete substitutes for any other version. `2.0.0` doesn't quite allow for this, because its hard cap at 3 places of version precision inherently loses information about forward and backward compatibility as more and more minor-level changes are added. As you will see, `SemVer 2.1` improves upon this model by explicitly declaring forward- and backward-compatibility with any other version in an easy-to-understand way. Given a hypothetical version `1.2.3`: - If making changes that are both forward- and backward-compatible with the current version (i.e. a bug fix), add `.1` to the far right of the version number. In this case: `1.2.3.1`. - If making changes that are backward-compatible but not forward-compatible with the current version (i.e. an addition to the API), increment the version number. In this case: `1.2.4`. - If making changes that are not backward-compatible with the current version (i.e. an API removal), increment the shortest part of the version number for which the changes are not backwards compatible, and drop the rest. - In this case, assuming the change is backwards-compatible with version `1` (but not version `1.2`): `1.3`. - Alternately, assuming the change isn't backward-compatible with any prior version: `2`. So, for example, if you used you used version `1.2` of our hypothetical piece of software in your code, you know that any version beginning with "1.2" will function fully as a drop-in replacement. So, in the above examples, `1.2.3`, `1.2.3.1` and `1.2.4` will work, but `1.3` and `2` won't. However, the true beauty of `SemVer 2.1` lies in its granularity: because version numbers can be of arbitrary length, you are able to know exactly which versions are compatible with (theoretically infinite) precision. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-06-08 20:29:19 -05:00

GiteaMirror closed this issue

2026-06-08 20:29:22 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#4107