[GH-ISSUE #1179] on "update my own dependencies without changing the public API" #2432

New Issue

GiteaMirror · 2026-04-20T10:25:59-05:00

GiteaMirror commented

2026-04-20 10:25:59 -05:00

Originally created by @Wouter1 on GitHub (Nov 24, 2025).
Original GitHub issue: https://github.com/semver/semver/issues/1179

This section on the semver.org is unclear in some cases

What should I do if I update my own dependencies without changing the public API?

That would be considered compatible since it does not affect the public API. Software that explicitly depends on the same dependencies as your package should have their own dependency specifications and the author will notice any conflicts. Determining whether the change is a patch level or minor level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality. We would usually expect additional code for the latter instance, in which case it’s obviously a minor level increment.

It is not clear how the version number needs to change if you ONLY change a dependency of the project, WITHOUT changing any other code. So there is no bug and no new functionality. If I follow the reasoning, the version should not even change. But then you can not make a new release.

The need to update dependencies happens for example in the following case.

Suppose the package P that you published depends on Q1.
At some time, there is a new version Q2. P does not need it, it works fine with Q1. But it would work with Q2 just as well, without any change in P.

However someone else who is using P wants also to use Q2. However his build system detects the version conflict between Q2 that he needs and the Q1 that P needs. So he asks you to update P to use Q2

Updating P to use Q2 is trivial. However you can't just re-release P using Q2 with the same version.
But nothing changed, there was not even a bug fix.

So what should be the new version for P?

Originally created by @Wouter1 on GitHub (Nov 24, 2025). Original GitHub issue: https://github.com/semver/semver/issues/1179 This section on the semver.org is unclear in some cases ``` What should I do if I update my own dependencies without changing the public API? That would be considered compatible since it does not affect the public API. Software that explicitly depends on the same dependencies as your package should have their own dependency specifications and the author will notice any conflicts. Determining whether the change is a patch level or minor level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality. We would usually expect additional code for the latter instance, in which case it’s obviously a minor level increment. ``` It is not clear how the version number needs to change if you ONLY change a dependency of the project, WITHOUT changing any other code. So there is no bug and no new functionality. If I follow the reasoning, the version should not even change. But then you can not make a new release. The need to update dependencies happens for example in the following case. Suppose the package P that you published depends on Q1. At some time, there is a new version Q2. P does not need it, it works fine with Q1. But it would work with Q2 just as well, without any change in P. However someone else who is using P wants also to use Q2. However his build system detects the version conflict between Q2 that he needs and the Q1 that P needs. So he asks you to update P to use Q2 Updating P to use Q2 is trivial. However you can't just re-release P using Q2 with the same version. But nothing changed, there was not even a bug fix. So what should be the new version for P?

GiteaMirror closed this issue

2026-04-20 10:25:59 -05:00

GiteaMirror commented

2026-04-20 10:26:00 -05:00

@zafarkhaja commented on GitHub (Nov 24, 2025):

There are only 3 numbers in a version, with the first 2 reserved for public API and functionality changes. So I'd say it leaves you with just one option, regardless of how confusing in this case the name "patch" is.

@zafarkhaja commented on GitHub (Nov 24, 2025): There are only 3 numbers in a version, with the first 2 reserved for public API and functionality changes. So I'd say it leaves you with just one option, regardless of how confusing in this case the name "patch" is.

GiteaMirror commented

2026-04-20 10:26:00 -05:00

@Wouter1 commented on GitHub (Nov 24, 2025):

@zafarkhaja yes this seems a reasonable guess and the one I'm using as a workaround while this issue is pending. But there are other options.

My point is that it's not documented properly how this should be handled.

@Wouter1 commented on GitHub (Nov 24, 2025): @zafarkhaja yes this seems a reasonable guess and the one I'm using as a workaround while this issue is pending. But there are other options. My point is that it's not documented properly how this should be handled.

GiteaMirror commented

2026-04-20 10:26:01 -05:00

@zafarkhaja commented on GitHub (Nov 24, 2025):

But there are other options.

Like what? At the end of the day, it depends on the value a new version of dependency brings and, more importantly, on your intentions. Because, remember, SemVer is also about communicating your intentions. If the library code doesn't change, why update? Maybe because they fixed a critical bug that affected your library (increment patch), or because they fixed a performance issue and you want to present this new performance boost as a desirable feature of your library (increment minor). It could also be the case that the new version of the dependency has both of the improvements but you don't care, you just prefer your dependencies up to date... or, like in your case somebody asks you to update (increment patch). Can't think of any other options.

My point is that it's not documented properly how this should be handled.

I agree, you could try adding another example to the FAQ section or rephrase the existing one, but in my opinion the real source of confusion which is the naming won't go away. I believe we should start from the naming and then provide generic rules which developers could extrapolate to infer a version in any situation.

@zafarkhaja commented on GitHub (Nov 24, 2025): > But there are other options. Like what? At the end of the day, it depends on the value a new version of dependency brings and, more importantly, on your intentions. Because, remember, SemVer is also about communicating your intentions. If the library code doesn't change, why update? Maybe because they fixed a critical bug that affected your library (increment patch), or because they fixed a performance issue and you want to present this new performance boost as a desirable feature of your library (increment minor). It could also be the case that the new version of the dependency has both of the improvements but you don't care, you just prefer your dependencies up to date... or, like in your case somebody asks you to update (increment patch). Can't think of any other options. > My point is that it's not documented properly how this should be handled. I agree, you could try adding another example to the FAQ section or rephrase the existing one, but in my opinion the real source of confusion which is the naming won't go away. I believe we should start from the naming and then provide generic rules which developers could extrapolate to infer a version in any situation.

GiteaMirror commented

2026-04-20 10:26:01 -05:00

@ljharb commented on GitHub (Nov 24, 2025):

A patch is for any change that's not major or minor, even if you just edit the readme.

@ljharb commented on GitHub (Nov 24, 2025): A patch is for *any* change that's not major or minor, even if you just edit the readme.

GiteaMirror commented

2026-04-20 10:26:02 -05:00

@steveklabnik commented on GitHub (Nov 25, 2025):

Yes, this would be a patch-level change. No API surface has changed.

@steveklabnik commented on GitHub (Nov 25, 2025): Yes, this would be a patch-level change. No API surface has changed.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#2432