[GH-ISSUE #191] Super versions #6119

New Issue

GiteaMirror · 2026-06-17T04:38:16-05:00

GiteaMirror commented

2026-06-17 04:38:16 -05:00

Originally created by @brettz9 on GitHub (Apr 9, 2014).
Original GitHub issue: https://github.com/semver/semver/issues/191

Hi,

Hopefully my idea is not coming too late here, but here goes...

I think that there is a compelling reason to support a "super" version prepended to the "version core" which conveys a more arbitrary but still somewhat meaningful grouping of "newness". This super version could perhaps in some cases be effectively ignored, but still give some meaningful sense to users.

The super version could reserve "0" to mean that the project is not (yet) meant to be consumed by the wider public. This may coincide with an unstable API as per a major version == 0 , but not necessarily, e.g., where the API is stable but the feature set is either too bare to be useful or is inadequate in level of testing for the organization to wish to freely associate itself with the budding project or experiment. Conversely, a product deemed polished enough to be publicly released and invite feedback but not yet with a stable API might use super version "1" with a major version of "0" (though a super version of "1" would in most cases probably coincide with a major version of at least "1").

A new super version may or may not map perfectly with new builds, and even where it does, a super version would be more convenient for reference than say forcing users to refer to the timestamp--even while a project might still find it useful to mark the meta-data of its builds with timestamps).

After 0, increments to the super version would simply indicate that the release was significant in some manner--whether or not backward-breaking changes have occurred. Projects might also associate a super version with distinct support (e.g., determining, by incrementing, that a snapshot was being made prior to which no new modifications would any longer be added).

Distinction might be made on whether the version core may be reset. When a new super version is created and the project wishes to reset the version core to 1.0.0 or 0.0.0, the super version might be followed by a ".". As with major or minor version changes causing the minor or patch version to increment, the super version joined in this manner conveys the sense that the major, minor, and patch versions will be reset. Conversely, if the project wishes to merely continue incrementing the version core components, and continue, for example, to give a clear picture of how many backward-breaking changes have occurred (by the preservation of the major version), the super version might instead be separated from the version core by a "-".

Usage scenarios

After its public release at 1.1.0.0, a project makes 5 new backward-breaking changes but does not consider that these changes really indicate anything pioneering enough to justify a super version increase. The version after these changes might end up as 1.6.0.0
After a public release at 1.1.0.0, a number of minor modifications have been added, leading to version 1.1.35.0, but deemed to be of a significant enough nature to merit an increment to the super version. Thus, instead of staying at 1.1.35.0, the project might release as 2.1.0.0. or 2-1.35.0.

While I know this is "semantic" versioning after all, besides carrying some semantic meaning of its own, a super version is, I believe, a very practical need along the lines of, but distinct from, the type of information conveyed by post-version meta-data.

Originally created by @brettz9 on GitHub (Apr 9, 2014). Original GitHub issue: https://github.com/semver/semver/issues/191 Hi, Hopefully my idea is not coming too late here, but here goes... I think that there is a compelling reason to support a "super" version _prepended_ to the "version core" which conveys a more arbitrary but still somewhat meaningful grouping of "newness". This super version could perhaps in some cases be effectively ignored, but still give some meaningful sense to users. The super version could reserve "0" to mean that the project is not (yet) meant to be consumed by the wider public. This may coincide with an unstable API as per a major version == 0 , but not necessarily, e.g., where the API is stable but the feature set is either too bare to be useful or is inadequate in level of testing for the organization to wish to freely associate itself with the budding project or experiment. Conversely, a product deemed polished enough to be publicly released and invite feedback but not yet with a stable API might use super version "1" with a major version of "0" (though a super version of "1" would in most cases probably coincide with a major version of at least "1"). A new super version may or may not map perfectly with new builds, and even where it does, a super version would be more convenient for reference than say forcing users to refer to the timestamp--even while a project might still find it useful to mark the meta-data of its builds with timestamps). **After 0, increments to the super version would simply indicate that the release was significant in some manner--whether or not backward-breaking changes have occurred.** Projects might also associate a super version with distinct support (e.g., determining, by incrementing, that a snapshot was being made prior to which no new modifications would any longer be added). Distinction might be made on whether the version core may be reset. When a new super version is created and the project wishes to reset the version core to 1.0.0 or 0.0.0, the super version might be followed by a ".". As with major or minor version changes causing the minor or patch version to increment, the super version joined in this manner conveys the sense that the major, minor, and patch versions will be reset. Conversely, if the project wishes to merely continue incrementing the version core components, and continue, for example, to give a clear picture of how many backward-breaking changes have occurred (by the preservation of the major version), the super version might instead be separated from the version core by a "-". _Usage scenarios_ 1. After its public release at 1.1.0.0, a project makes 5 new backward-breaking changes but does not consider that these changes really indicate anything pioneering enough to justify a super version increase. The version after these changes might end up as 1.6.0.0 2. After a public release at 1.1.0.0, a number of minor modifications have been added, leading to version 1.1.35.0, but deemed to be of a significant enough nature to merit an increment to the super version. Thus, instead of staying at 1.1.35.0, the project might release as 2.1.0.0. or 2-1.35.0. While I know this is "semantic" versioning after all, besides carrying some semantic meaning of its own, a super version is, I believe, a very practical need along the lines of, but distinct from, the type of information conveyed by post-version meta-data.

GiteaMirror added the question staled labels 2026-06-17 04:38:16 -05:00

GiteaMirror closed this issue

2026-06-17 04:38:18 -05:00

GiteaMirror commented

2026-06-17 04:38:18 -05:00

@FichteFoll commented on GitHub (Apr 9, 2014):

I didn't read everything, but to my understanding the build component is sufficient for what you would use a "super version number" for. Your second example contradicts the useage of semantic versions completely and the first should actually never happen.

@FichteFoll commented on GitHub (Apr 9, 2014): I didn't read everything, but to my understanding the `build` component is sufficient for what you would use a "super version number" for. Your second example contradicts the useage of semantic versions completely and the first _should_ actually never happen.

GiteaMirror commented

2026-06-17 04:38:19 -05:00

@brettz9 commented on GitHub (Apr 9, 2014):

All breaking changes should never happen at all but they do. Moreover, an API may be quite large, and with a project that is careful and diligent enough to indicate when some breaking change or other occurs (e.g., a long deprecated argument is dropped, an error object is modified such that code relying on its obscure properties would be tripped up by the changes), the incrementing can happen quickly.

Yes, I know the build component can be leveraged to convey similar information, but:

I mentioned cases where one may wish to have a super version distinct from the build (e.g., when the build is a date, whereas one also wishes a more user-friendly version number).
It is hardly adequate to convey version numbers to the wider public (as opposed to say developers) which don't begin with the most salient information first.

I certainly don't see any contradiction in my semantic+super version usage since the super version is distinct in nature from the other components. Note, I am not causing the minor changes to be rolled into a new major version, but rather into a new super version.

@brettz9 commented on GitHub (Apr 9, 2014): All breaking changes _should_ never happen at all but they do. Moreover, an API may be quite large, and with a project that is careful and diligent enough to indicate when some breaking change or other occurs (e.g., a long deprecated argument is dropped, an error object is modified such that code relying on its obscure properties would be tripped up by the changes), the incrementing can happen quickly. Yes, I know the `build` component can be leveraged to convey similar information, but: 1. I mentioned cases where one may wish to have a super version distinct from the build (e.g., when the build is a date, whereas one also wishes a more user-friendly version number). 2. It is hardly adequate to convey version numbers to the wider public (as opposed to say developers) which don't begin with the most salient information first. I certainly don't see any contradiction in my semantic+super version usage since the super version is distinct in nature from the other components. Note, I am not causing the minor changes to be rolled into a new major version, but rather into a new super version.

GiteaMirror commented

2026-06-17 04:38:19 -05:00

@crazedsanity commented on GitHub (Apr 10, 2014):

All of your examples give the last bit of the version number as "0", so I wonder if it would be better to simply use the major.minor.patch syntax. Use that last part, the metadata, for extra information.

The explanation is a bit confusing, almost indicating that the "super" version is of paramount importance and possible of no importance. It's position in the version number makes it easy to confuse with a standard version string, meaning it would be difficult (at best) to understand whether there's a "super version" scheme in place or not.

@crazedsanity commented on GitHub (Apr 10, 2014): All of your examples give the last bit of the version number as "0", so I wonder if it would be better to simply use the `major.minor.patch` syntax. Use that last part, the metadata, for extra information. The explanation is a bit confusing, almost indicating that the "super" version is of paramount importance and possible of no importance. It's position in the version number makes it easy to confuse with a standard version string, meaning it would be difficult (at best) to understand whether there's a "super version" scheme in place or not.

GiteaMirror commented

2026-06-17 04:38:19 -05:00

@crazedsanity commented on GitHub (Apr 10, 2014):

A project as massive as indicated by @brettz9 seems like it would benefit from being broken into smaller bits. Each bit could then be versioned separately; a larger "conglomeration" of those libraries (equivalent to the original, massive project) could contain its own version number, which gets incremented based on what sort of changes occur in the smaller bits.

@crazedsanity commented on GitHub (Apr 10, 2014): A project as massive as indicated by @brettz9 seems like it would benefit from being broken into smaller bits. Each bit could then be versioned separately; a larger "conglomeration" of those libraries (equivalent to the original, massive project) could contain its own version number, which gets incremented based on what sort of changes occur in the smaller bits.

GiteaMirror commented

2026-06-17 04:38:19 -05:00

@brettz9 commented on GitHub (Apr 10, 2014):

The last bit would be, as before, for patches. If a new super version was patched (without an increase in the minor or major version), it would be incremented, just as is the case of a major version allowing increments to the patch when there is no increase in minor version.

So after a public release and stable API (to 1.1.0.0), a project then makes 2 major changes, then 4 minor ones on top of the last major one, and then 6 patches on top of the last minor one, the version will become 1.3.4.6.

The importance of the "super" version, beyond the "0", would be decided by the project. It is not so strongly "semantic" as for the major, minor, or patch versions, if "semantic" (i.e., meaningful), is taken to speak of a wholly, independently discernible meaning, but it is meaningful to the numberless projects which still use their own form of non-"semantic" versioning because they do wish to convey the meaning to their users that some new release really is a big step forward in terms of usability to people familiar with the project.

As far as confusability, maybe being prefixed with "-" instead of "." would help with that, but one should be able to note whether there are 4 vs. 3 numbers.

Also, my personal interest in this is actually for smaller projects with frequent releases, though I think it ought to appeal to big projects.

While separate projects for major new "super" versions can work to some degree, that is not so convenient for people who say just want to keep using their old routine to update to the absolute latest version in the repository.

@brettz9 commented on GitHub (Apr 10, 2014): The last bit would be, as before, for patches. If a new super version was patched (without an increase in the minor or major version), it would be incremented, just as is the case of a major version allowing increments to the patch when there is no increase in minor version. So after a public release and stable API (to 1.1.0.0), a project then makes 2 major changes, then 4 minor ones on top of the last major one, and then 6 patches on top of the last minor one, the version will become 1.3.4.6. The importance of the "super" version, beyond the "0", would be decided by the project. It is not so strongly "semantic" as for the major, minor, or patch versions, if "semantic" (i.e., meaningful), is taken to speak of a wholly, independently discernible meaning, but it is meaningful to the numberless projects which still use their own form of non-"semantic" versioning because they do wish to convey the meaning to their users that some new release really is a big step forward in terms of usability to people familiar with the project. As far as confusability, maybe being prefixed with "-" instead of "." would help with that, but one should be able to note whether there are 4 vs. 3 numbers. Also, my personal interest in this is actually for smaller projects with frequent releases, though I think it ought to appeal to big projects. While separate projects for major new "super" versions can work to some degree, that is not so convenient for people who say just want to keep using their old routine to update to the absolute latest version in the repository.

GiteaMirror commented

2026-06-17 04:38:20 -05:00

@brettz9 commented on GitHub (Apr 10, 2014):

If you think you have a good system going, and you would like to see it become more commonplace, I think you have to accommodate the majority of use cases; the use of such admittedly somewhat arbitrary versions is not only commonplace but helpful.

If my little project that releases monthly makes a small breaking change every month for 5 months, when Joe Public comes around 5 months later seeing the version now at 6.0.0 and says, "Wow, I should really add time to my very busy schedule to try this out now because it must have improved a lot" that could well be a disservice to him.

On the other hand, if a project indeed has say made a lot of "minor" changes but adding a lot of functionality, bringing the version to say, 1.8.0, someone looking at the static, so-called "major" version might be deceived into thinking no major (i.e., important) changes have occurred.

A prominent super version would avoid both of these problems, particularly for the general public who is unaware of the meaning of each component, but it also conveys a useful sense to developers as well.

@brettz9 commented on GitHub (Apr 10, 2014): If you think you have a good system going, and you would like to see it become more commonplace, I think you have to accommodate the majority of use cases; the use of such admittedly _somewhat_ arbitrary versions is not only commonplace but helpful. If my little project that releases monthly makes a small breaking change every month for 5 months, when Joe Public comes around 5 months later seeing the version now at 6.0.0 and says, "Wow, I should really add time to my very busy schedule to try this out now because it must have improved a lot" that could well be a disservice to him. On the other hand, if a project indeed has say made a lot of "minor" changes but adding a lot of functionality, bringing the version to say, 1.8.0, someone looking at the static, so-called "major" version might be deceived into thinking no major (i.e., important) changes have occurred. A prominent super version would avoid both of these problems, particularly for the general public who is unaware of the meaning of each component, but it also conveys a useful sense to developers as well.

GiteaMirror commented

2026-06-17 04:38:21 -05:00

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

@brettz9, it does not appear that any changes to the SemVer spec are required here. You are free to pre/post-pend anything you like to the version string, provided you supply white space between your non-conforming bits and the SemVer bits.

There is considerable resistance to adding additional fields to the version triplet, and it very unlikely that your proposal will be accepted. Please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Dec 6, 2017): @brettz9, it does not appear that any changes to the SemVer spec are required here. You are free to pre/post-pend anything you like to the version string, provided you supply white space between your non-conforming bits and the SemVer bits. There is considerable resistance to adding additional fields to the version triplet, and it very unlikely that your proposal will be accepted. Please close this issue at your earliest possible convenience.

GiteaMirror commented

2026-06-17 04:38:21 -05:00

@brettz9 commented on GitHub (Dec 6, 2017):

If there is considerable resistance, then let it be expressed here as you have done. The owner is welcome to close the issue, but I'd otherwise like for it to be available for discussion.

(FWIW, I'd also like to see an alternative syntax which may be even less likely to be adopted but which I also feel would be practical: making the major, minor and patch versions independent such that 1.3.5 could progress directly to 1.4.5 (or even 2.3.5 or 2.4.5) with the practical effect that one trusting the issuers of the semver would be confident that the new major and minor version (telegraphing breaking changes and new features respectively) did not signify any fixes in bugs, and thus people could avoid an update if they were concerned about bugs only. While some go through the trouble of continuing to support older versions and making patches for them, for those projects which don't do so, it would help to at least have semantic numbering which actually makes clear whether a minor version change also includes bug fixes or not.)

@brettz9 commented on GitHub (Dec 6, 2017): If there is considerable resistance, then let it be expressed here as you have done. The owner is welcome to close the issue, but I'd otherwise like for it to be available for discussion. (FWIW, I'd also like to see an alternative syntax which may be even less likely to be adopted but which I also feel would be practical: making the major, minor and patch versions independent such that `1.3.5` could progress directly to `1.4.5` (or even `2.3.5` or `2.4.5`) with the practical effect that one trusting the issuers of the semver would be confident that the new major and minor version (telegraphing breaking changes and new features respectively) did not signify any fixes in bugs, and thus people could avoid an update if they were concerned about bugs only. While some go through the trouble of continuing to support older versions and making patches for them, for those projects which don't do so, it would help to at least have semantic numbering which actually makes clear whether a minor version change also includes bug fixes or not.)

GiteaMirror commented

2026-06-17 04:38:21 -05:00

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

Ya, I think we could describe a kind of version meta string that is independent of SemVer and other versioning schemes, which could be used to link to a version schema that provided exactly the kind of information you want to know about that specific version number. For instance, whether the developers follow a fix-bugs first policy and then add features, or if they mix them all in together. The goal would be to provide enough information that automation could easily and safely map between different kinds of version strings. Kind of an ISO-9xxx Super-Light.

@jwdonahue commented on GitHub (Dec 6, 2017): Ya, I think we could describe a kind of version meta string that is independent of SemVer and other versioning schemes, which could be used to link to a version schema that provided exactly the kind of information you want to know about that specific version number. For instance, whether the developers follow a fix-bugs first policy and then add features, or if they mix them all in together. The goal would be to provide enough information that automation could easily and safely map between different kinds of version strings. Kind of an ISO-9xxx Super-Light.

GiteaMirror commented

2026-06-17 04:38:22 -05:00

@jwdonahue commented on GitHub (Oct 8, 2018):

@brettz9 , FYI: VersionMeta and VersionSchema.

@jwdonahue commented on GitHub (Oct 8, 2018): @brettz9 , FYI: [VersionMeta](https://versionmeta.org/) and [VersionSchema](http://versionschema.org/).

GiteaMirror commented

2026-06-17 04:38:22 -05:00

@brettz9 commented on GitHub (Oct 11, 2018):

Great, look forward to trying to get a closer look...

@brettz9 commented on GitHub (Oct 11, 2018): Great, look forward to trying to get a closer look...

GiteaMirror commented

2026-06-17 04:38:22 -05:00

@jwdonahue commented on GitHub (Oct 11, 2018):

@brettz9, fixed. Thanks.

@jwdonahue commented on GitHub (Oct 11, 2018): @brettz9, fixed. Thanks.

GiteaMirror commented

2026-06-17 04:38:23 -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 contribution, 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 contribution, you're amazing :fireworks:

GiteaMirror commented

2026-06-17 04:38:24 -05:00

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

👻 👻 👻
Closed as staled

@alexandrtovmach commented on GitHub (Jun 19, 2020): 👻 👻 👻 Closed as staled

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#6119