[GH-ISSUE #250] Seperating structural and change semantics #7149

New Issue

GiteaMirror · 2026-06-20T16:58:56-05:00

GiteaMirror commented

2026-06-20 16:58:56 -05:00

Originally created by @EddieGarmon on GitHub (Apr 22, 2015).
Original GitHub issue: https://github.com/semver/semver/issues/250

The more I talk to people about SemVer, the more I explicitly separate the structural semantics from the change semantics.

I think that defining these concepts separately helps alleviate a lot of the pains on when to do what, and how to handle 0.Y.Z versions in a manner that adds the most value for downstream consumers.

How about something like the following?

Summary

A semantic version structurally has:

A defined public API that it is representing.
Three integer parts in the format X.Y.Z.
When X is zero (0), the API should be considered volatile, but consumption is not discouraged. Once the API is generally stable, X should move from zero.
Additional labels for pre-release and build metadata are available as extensions but are not part of the version proper.

When comparing two semantic version numbers, you can always tell what type of API change should be expected, which should be one of:

Breaking, when any backwards incompatible changes are introduced to the public API.
- if (X >= 1) then increment X and reset Y and Z to zero
- if (X == 0) then increment Y and reset Z to zero
Additive, when new, backwards compatible functionality is introduced to the public API.
- if (X >= 1) then increment Y and reset Z to zero
- if (X == 0) then increment Z
Repackaging, when backwards compatible bug fixes are introduced or the API is repackaged for distribution
- if (X >= 1) then increment Z
- if (X == 0) not allowed on volatile APIs

Originally created by @EddieGarmon on GitHub (Apr 22, 2015). Original GitHub issue: https://github.com/semver/semver/issues/250 The more I talk to people about SemVer, the more I explicitly separate the structural semantics from the change semantics. I think that defining these concepts separately helps alleviate a lot of the pains on when to do what, and how to handle 0.Y.Z versions in a manner that adds the most value for downstream consumers. How about something like the following? ## ## Summary A semantic version structurally has: - A defined public API that it is representing. - Three integer parts in the format X.Y.Z. - When X is zero (0), the API should be considered volatile, but consumption is not discouraged. Once the API is generally stable, X should move from zero. - Additional labels for pre-release and build metadata are available as extensions but are not part of the version proper. When comparing two semantic version numbers, you can always tell what type of API change should be expected, which should be one of: - Breaking, when any backwards incompatible changes are introduced to the public API. - if (X >= 1) then increment X and reset Y and Z to zero - if (X == 0) then increment Y and reset Z to zero - Additive, when new, backwards compatible functionality is introduced to the public API. - if (X >= 1) then increment Y and reset Z to zero - if (X == 0) then increment Z - Repackaging, when backwards compatible bug fixes are introduced or the API is repackaged for distribution - if (X >= 1) then increment Z - if (X == 0) not allowed on volatile APIs

GiteaMirror added the question waiting for PR labels 2026-06-20 16:58:57 -05:00

GiteaMirror closed this issue

2026-06-20 16:58:59 -05:00

GiteaMirror commented

2026-06-20 16:59:00 -05:00

@Ericson2314 commented on GitHub (Jun 28, 2015):

The JSON RFC does a good job of this, introducing groups of non-terminals with a description of their semantic meaning.

@Ericson2314 commented on GitHub (Jun 28, 2015): The JSON RFC does a good job of this, introducing groups of non-terminals with a description of their semantic meaning.

GiteaMirror commented

2026-06-20 16:59:00 -05:00

@jwdonahue commented on GitHub (Dec 8, 2017):

@EddieGarmon, that appears to be one state machine that is compliant with SemVer, but there are others as well. For instance, according the spec, you can have 0.0.0-n. Unless you intend to issue a PR related to this issue or have further comments/questions, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Dec 8, 2017): @EddieGarmon, that appears to be one state machine that is compliant with SemVer, but there are others as well. For instance, according the spec, you can have 0.0.0-n. Unless you intend to issue a PR related to this issue or have further comments/questions, please close this issue at your earliest possible convenience.

GiteaMirror commented

2026-06-20 16:59:01 -05:00

@alexandrtovmach commented on GitHub (Jun 10, 2020):

This issue looks staled and will be closed in 10 days if there are no objections. Thanks everyone for contributions, you're amazing 🎆

@alexandrtovmach commented on GitHub (Jun 10, 2020): This issue looks staled and will be closed in 10 days if there are no objections. Thanks everyone for contributions, you're amazing :fireworks:

GiteaMirror commented

2026-06-20 16:59:02 -05:00

@EddieGarmon commented on GitHub (Jun 11, 2020):

This has not been addressed, why close?

@EddieGarmon commented on GitHub (Jun 11, 2020): This has not been addressed, why close?

GiteaMirror commented

2026-06-20 16:59:03 -05:00

@alexandrtovmach commented on GitHub (Jun 11, 2020):

@EddieGarmon Thanks for reaching out 👍 Last comment was added 2 years ago, so it's kind of "staled", do you agree? 😄

I'm just trying to clean-up current list of tasks from everything that's not actual anymore #573. I removed "staled" label, and will keep on this issue after urgent things

@alexandrtovmach commented on GitHub (Jun 11, 2020): @EddieGarmon Thanks for reaching out 👍 Last comment was added 2 years ago, so it's kind of "staled", do you agree? 😄 I'm just trying to clean-up current list of tasks from everything that's not actual anymore #573. I removed "staled" label, and will keep on this issue after urgent things

GiteaMirror commented

2026-06-20 16:59:04 -05:00

@alexandrtovmach commented on GitHub (May 14, 2021):

SemVer spec is something stable and strict, and if you want to change it, please create fork or start another project

closing in favor of https://github.com/semver/semver/issues/703#issuecomment-841420754

@alexandrtovmach commented on GitHub (May 14, 2021): >SemVer spec is something stable and strict, and if you want to change it, please create fork or start another project closing in favor of https://github.com/semver/semver/issues/703#issuecomment-841420754

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#7149