[GH-ISSUE #349] Suggestion for minor releases to disallow adding new externally-accessible API #5373

New Issue

GiteaMirror · 2026-06-15T11:43:51-05:00

GiteaMirror commented

2026-06-15 11:43:51 -05:00

Originally created by @Boberski on GitHub (Jan 5, 2017).
Original GitHub issue: https://github.com/semver/semver/issues/349

I would like to suggest for a future enhancement, for minor releases to disallow the adding of new externally-accessible API. Instead requiring that the major version be incremented in these cases. The goal being, to additionally convey potentially security-relevant information.

Briefly, often times security testing such as secure code review or penetration testing is limited to being performed only for major releases. However, most people not familiar with semantic versioning anecdotally perhaps think minor corresponds more closely to the definition of a patch.

Attack surface in semantic-versioned code can jump significantly in minor releases. Adjusting the definition would make it easier to detect when attack surface changes occur, to help stakeholders make better-informed decisions as to the timing and frequency of security testing for releases.

There are perhaps a couple ways to do this, for example:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API or if any new externally-accessible API are added. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.

Originally created by @Boberski on GitHub (Jan 5, 2017). Original GitHub issue: https://github.com/semver/semver/issues/349 I would like to suggest for a future enhancement, for minor releases to disallow the adding of new externally-accessible API. Instead requiring that the major version be incremented in these cases. The goal being, to additionally convey potentially security-relevant information. Briefly, often times security testing such as secure code review or penetration testing is limited to being performed only for major releases. However, most people not familiar with semantic versioning anecdotally perhaps think minor corresponds more closely to the definition of a patch. Attack surface in semantic-versioned code can jump significantly in minor releases. Adjusting the definition would make it easier to detect when attack surface changes occur, to help stakeholders make better-informed decisions as to the timing and frequency of security testing for releases. There are perhaps a couple ways to do this, for example: 8. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API **_or if any new externally-accessible API are added_**. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.

GiteaMirror closed this issue

2026-06-15 11:43:52 -05:00

GiteaMirror commented

2026-06-15 11:43:53 -05:00

@FichteFoll commented on GitHub (Jan 10, 2017):

Public API == externally accessible API. Your change which would make the entire minor section pretty much useless.

@FichteFoll commented on GitHub (Jan 10, 2017): Public API == externally accessible API. Your change which would make the entire minor section pretty much useless.

GiteaMirror commented

2026-06-15 11:43:54 -05:00

@Boberski commented on GitHub (Jan 10, 2017):

Thank you for taking the time to review.

I guess I could have alternately more simply written "[...] or if any new public API are added." Was trying to emphasize new-ness and external-ness, a little overly-verbose maybe.

But yes the goal would be to limit the minor section's use to any new functionality or improvements to existing public API, along with private code etc. as currently defined.

@Boberski commented on GitHub (Jan 10, 2017): Thank you for taking the time to review. I guess I could have alternately more simply written "[...] or if any new public API are added." Was trying to emphasize new-ness and external-ness, a little overly-verbose maybe. But yes the goal would be to limit the minor section's use to any new functionality or improvements to **_existing_** public API, along with private code etc. as currently defined.

GiteaMirror commented

2026-06-15 11:43:55 -05:00

@FichteFoll commented on GitHub (Jan 12, 2017):

It seems to me like you're not abstracting enough. Adding new functionality to exist API is still adding something to the API.

A concrete example for this (and probably something you are thinking about) would be adding a new parameter to a function, which offers new functionality, i.e. adding the reverse parameter to a sort function.

If you remove this asset of minor releases, the entire category becomes useless because any change would either fall into patch or into major category. Or maybe you could illustrate an example where one would increase the minor version with your suggestion?

@FichteFoll commented on GitHub (Jan 12, 2017): It seems to me like you're not abstracting enough. Adding new functionality to exist API is still adding something to the API. A concrete example for this (and probably something you are thinking about) would be adding a new parameter to a function, which offers new functionality, i.e. adding the `reverse` parameter to a `sort` function. If you remove this asset of minor releases, the entire category becomes useless because any change would either fall into patch or into major category. Or maybe you could illustrate an example where one would increase the minor version with your suggestion?

GiteaMirror commented

2026-06-15 11:43:55 -05:00

@jwdonahue commented on GitHub (Nov 29, 2017):

@Boberski this seems to be more of a user education issue. For security critical code, any change in any of the packages you depend on, should trigger a full review and test cycle prior to acceptance of the changes. Security critical code should not rely on third party adherence to the SemVer spec, even if said parties have a stellar reputation, eventually, somebody is going to screw something up.

Unless you wish to provide additional arguments in support of this proposed change, can you please close this issue?

@jwdonahue commented on GitHub (Nov 29, 2017): @Boberski this seems to be more of a user education issue. For security critical code, any change in any of the packages you depend on, should trigger a full review and test cycle prior to acceptance of the changes. Security critical code should not rely on third party adherence to the SemVer spec, even if said parties have a stellar reputation, eventually, somebody is going to screw something up. Unless you wish to provide additional arguments in support of this proposed change, can you please close this issue?

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#5373