[GH-ISSUE #80] When your Public API is in my Public API #2775

New Issue

GiteaMirror · 2026-04-25T16:39:58-05:00

GiteaMirror commented

2026-04-25 16:39:58 -05:00

Originally created by @EddieGarmon on GitHub (Mar 15, 2013).
Original GitHub issue: https://github.com/semver/semver/issues/80

The current specification is great when you completely control all of the Public API. If instead, you also export parts of another Public API (consume or produce), you should also take into account any version changes of that consumed API when updating.

I propose the following for discussion:
Use the greater of the API changes in both yours and the exported API, as your next API change reason.

Using the exact same mechanic as currently defined:

Bug fixes not affecting the API increment the patch version -> Private Change
Backwards compatible API additions/changes increment the minor version -> Compatible Change
Backwards incompatible API changes increment the major version -> Incompatible Change

An example:

You release 1.0.0, exporting part of component X at version 5.7.11
You need to release a minor update, in the same time X has versioned to 7.11.13
Therefore to produce a compatible 1.1.0 release, you can not update you dependency on X.
If you do update your dependency on X, you must also use an Incompatible Change update mechanic in your next release, meaning version 2.0.0

Originally created by @EddieGarmon on GitHub (Mar 15, 2013). Original GitHub issue: https://github.com/semver/semver/issues/80 The current specification is great when you completely control all of the Public API. If instead, you also export parts of another Public API (consume or produce), you should also take into account any version changes of that consumed API when updating. I propose the following for discussion: Use the greater of the API changes in both yours and the exported API, as your next API change reason. Using the exact same mechanic as currently defined: - Bug fixes not affecting the API increment the patch version -> Private Change - Backwards compatible API additions/changes increment the minor version -> Compatible Change - Backwards incompatible API changes increment the major version -> Incompatible Change An example: - You release 1.0.0, exporting part of component X at version 5.7.11 - You need to release a minor update, in the same time X has versioned to 7.11.13 - Therefore to produce a compatible 1.1.0 release, you can not update you dependency on X. - If you do update your dependency on X, you must also use an Incompatible Change update mechanic in your next release, meaning version 2.0.0

GiteaMirror closed this issue

2026-04-25 16:39:58 -05:00

GiteaMirror commented

2026-04-25 16:40:00 -05:00

@colin-haber commented on GitHub (Mar 17, 2013):

Honestly, I've run into this problem as SemVer prepares to update to RC2. The way I see it, as long as the API you expose doesn't change, then there's no reason to update the version for your library. If you're implementing or using external APIs, however, including a reference to their version in your library somewhere would be nice.

As RC2 will be creating backwards-incompatible changes, (mostly regarding build metadata,) I'll be bumping the major version number on my SemVer lib. I think we're saying the same thing, in which case, I don't see why anything additional needs to be added to the spec.

@colin-haber commented on GitHub (Mar 17, 2013): Honestly, I've run into this problem as SemVer prepares to update to RC2. The way I see it, as long as the API _you_ expose doesn't change, then there's no reason to update the version for _your_ library. If you're implementing or using external APIs, however, including a reference to their version in your library somewhere would be nice. As RC2 will be creating backwards-incompatible changes, (mostly regarding build metadata,) I'll be bumping the major version number on my SemVer lib. I think we're saying the same thing, in which case, I don't see why anything additional needs to be added to the spec.

GiteaMirror commented

2026-04-25 16:40:01 -05:00

@jeffhandley commented on GitHub (Apr 30, 2013):

If you have a dependency whose version has made a major change, but you are only making a minor change, I think it's perfectly fine to only make a minor bump to your own version number. The consumer of the dependency would identify that the dependency had a major version change, and it may or may not affect them.

I don't think additional notes are needed in the spec for this, but we could put this into a FAQ that is an addendum to the spec itself.

@jeffhandley commented on GitHub (Apr 30, 2013): If you have a dependency whose version has made a major change, but you are only making a minor change, I think it's perfectly fine to only make a minor bump to your own version number. The consumer of the dependency would identify that the _dependency_ had a major version change, and it may or may not affect them. I don't think additional notes are needed in the spec for this, but we could put this into a FAQ that is an addendum to the spec itself.

GiteaMirror commented

2026-04-25 16:40:02 -05:00

@haacked commented on GitHub (May 6, 2013):

I'm going to close this issue for now. If anyone wants to take a crack at making an addendum to the FAQ, please submit a PR with the proposed change and I'd be happy to look at it.

@haacked commented on GitHub (May 6, 2013): I'm going to close this issue for now. If anyone wants to take a crack at making an addendum to the FAQ, please submit a PR with the proposed change and I'd be happy to look at it.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#2775