github-starred/semver
2
0
Fork 0
mirror of https://github.com/semver/semver.git synced 2026-07-11 08:02:23 -05:00
Code Issues 1.0k Packages Projects Releases 4 Wiki Activity

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

New Issue
Closed
opened 2026-04-16 10:14:36 -05:00 by GiteaMirror · 6 comments
GiteaMirror commented 2026-04-16 10:14:36 -05:00
Owner
Copy Link

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 questionwaiting for PR labels 2026-04-16 10:14:36 -05:00
GiteaMirror commented 2026-04-16 10:14:38 -05:00
Author
Owner
Copy Link

@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.

<!-- gh-comment-id:116354608 --> @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-04-16 10:14:38 -05:00
Author
Owner
Copy Link

@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.

<!-- gh-comment-id:350171796 --> @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-04-16 10:14:38 -05:00
Author
Owner
Copy Link

@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 🎆

<!-- gh-comment-id:642140666 --> @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-04-16 10:14:39 -05:00
Author
Owner
Copy Link

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

This has not been addressed, why close?

<!-- gh-comment-id:642768417 --> @EddieGarmon commented on GitHub (Jun 11, 2020): This has not been addressed, why close?
GiteaMirror commented 2026-04-16 10:14:39 -05:00
Author
Owner
Copy Link

@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

<!-- gh-comment-id:642790900 --> @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-04-16 10:14:40 -05:00
Author
Owner
Copy Link

@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

<!-- gh-comment-id:841435984 --> @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.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
consensus seeking
duplicate
extend
layout
pull-request
Mirrored from GitHub Pull Request
 question
RFC
spelling/grammar
staled
update
waiting for PR
won't fix
No Label question waiting for PR
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/semver#1041
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?