[GH-ISSUE #248] Change is potentially breaking- only breaks invalid usage. #7147

New Issue

GiteaMirror · 2026-06-20T16:58:52-05:00

GiteaMirror commented

2026-06-20 16:58:52 -05:00

Originally created by @Lucretiel on GitHub (Mar 18, 2015).
Original GitHub issue: https://github.com/semver/semver/issues/248

Let's say I have a function that wraps python's print:

def print_wrap(*args, **kwargs):  # Standard python idiom for forwarding args
    print(*args, **kwargs)

This is version 1.0.0. If I extend the method with an additional kwarg, like so:

def print_wrap(*args, thing, **kwargs):
    # Do something with thing
    print(*args, **kwargs)

Would this necessitate a bump to 1.1.0 or 2.0.0? The added feature is pure extension- any correctly written code would be completely backwards compatible, because print doesn't expect a thing kwarg. However, if someone had written this:

print_wrap(thing='hello')

This would result in print raising a TypeError exception in 1.0.0, but it would invoke the new thing behavior in the new version- technically, a breaking change. Does the fact that this print_wrap example is incorrect usage mean that I can consider this a backwards compatible change? I couldn't find any clear guidance in the current semver release.

Originally created by @Lucretiel on GitHub (Mar 18, 2015). Original GitHub issue: https://github.com/semver/semver/issues/248 Let's say I have a function that wraps python's print: ``` def print_wrap(*args, **kwargs): # Standard python idiom for forwarding args print(*args, **kwargs) ``` This is version 1.0.0. If I extend the method with an additional kwarg, like so: ``` def print_wrap(*args, thing, **kwargs): # Do something with thing print(*args, **kwargs) ``` Would this necessitate a bump to 1.1.0 or 2.0.0? The added feature is pure extension- any correctly written code would be completely backwards compatible, because `print` doesn't expect a `thing` kwarg. However, if someone had written this: ``` print_wrap(thing='hello') ``` This would result in `print` raising a `TypeError` exception in 1.0.0, but it would invoke the new `thing` behavior in the new version- technically, a breaking change. Does the fact that this `print_wrap` example is incorrect usage mean that I can consider this a backwards compatible change? I couldn't find any clear guidance in the current semver release.

GiteaMirror closed this issue

2026-06-20 16:58:52 -05:00

GiteaMirror commented

2026-06-20 16:58:53 -05:00

@FichteFoll commented on GitHub (Mar 18, 2015):

Since a major increase is required for breaking changes to the public API, it raises the following core question: "What is the public API?"

So in your particular case it would probably be "Is the old behavior documented?" (likely it's not). An example for this would be "any other parameter will definitely raise TypeError" or similar.

Also, since you are technically adding a parameter to a function here you are not really breaking old functionality, you are adding some. It would basically be impossible to add anything to a module in a minor release because a user "could be accessing this particular attribute of the module and expect an AttributeError".

@FichteFoll commented on GitHub (Mar 18, 2015): Since a major increase is required for breaking changes to the public API, it raises the following core question: "What is the public API?" So in your particular case it would probably be "Is the old behavior documented?" (likely it's not). An example for this would be "any other parameter will _definitely_ raise TypeError" or similar. Also, since you are technically adding a parameter to a function here you are not really breaking old functionality, you are adding some. It would basically be impossible to add anything to a module in a minor release because a user "could be accessing this particular attribute of the module and expect an AttributeError".

GiteaMirror commented

2026-06-20 16:58:54 -05:00

@PaulMag commented on GitHub (Sep 14, 2015):

I agree with FichteFoll that this is not considered a breaking change unless you have specifically stated in the public what should happen before.

""
It would basically be impossible to add anything to a module in a minor release because a user "could be accessing this particular attribute of the module and expect an AttributeError".
"""
Exactly. :)

@PaulMag commented on GitHub (Sep 14, 2015): I agree with FichteFoll that this is not considered a breaking change unless you have specifically stated in the public what should happen before. "" It would basically be impossible to add anything to a module in a minor release because a user "could be accessing this particular attribute of the module and expect an AttributeError". """ Exactly. :)

GiteaMirror commented

2026-06-20 16:58:54 -05:00

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

@Lucretiel, it's clear you have back-compat, bump the minor version for the new feature.

If you have no further questions on this matter, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Dec 8, 2017): @Lucretiel, it's clear you have back-compat, bump the minor version for the new feature. If you have no further questions on this matter, please close this issue at your earliest possible convenience.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#7147