[GH-ISSUE #132] Missing: Major version MUST be incremented if the system behaviour changes in a backwards incompatible manner #2800

New Issue

GiteaMirror · 2026-04-25T16:43:53-05:00

GiteaMirror commented

2026-04-25 16:43:53 -05:00

Originally created by @FrVaBe on GitHub (Jul 4, 2013).
Original GitHub issue: https://github.com/semver/semver/issues/132

If (public) API is ment as the way the system interacts with other components then the major number MUST also be incremented if the system behaviour changes in an backwards incompatible manner - even without API changes.

E.g. if the system offers a save API method which behaves like an update operation so far but than changes to be an create or update operation.

Originally created by @FrVaBe on GitHub (Jul 4, 2013). Original GitHub issue: https://github.com/semver/semver/issues/132 If (public) API is ment as the way the system interacts with other components then the major number MUST also be incremented if the system **behaviour** changes in an backwards incompatible manner - even without API changes. E.g. if the system offers a `save` API method which behaves like an `update` operation so far but than changes to be an `create or update` operation.

GiteaMirror closed this issue

2026-04-25 16:43:53 -05:00

GiteaMirror commented

2026-04-25 16:43:54 -05:00

@FrVaBe commented on GitHub (Jul 4, 2013):

I am not quite sure about the meaning of term API here. After reading the document again it seems that it is not only meant as the way how to intercat with a system but also about the functionality that is expected. In this case changing the functionality - even without changing the way how to interact - is of course an API change so the issue could be closed. Would be nice if someone would do some clarification for me ;-)

@FrVaBe commented on GitHub (Jul 4, 2013): I am not quite sure about the meaning of term _API_ here. After reading the document again it seems that it is not only meant as the way _how_ to intercat with a system but also about the functionality that is expected. In this case changing the functionality - even without changing the way how to interact - is of course an API change so the issue could be closed. Would be nice if someone would do some clarification for me ;-)

GiteaMirror commented

2026-04-25 16:43:54 -05:00

@EddieGarmon commented on GitHub (Jul 18, 2013):

I think the understanding of what Public API is probably needs a FAQ entry. Generally for specifications, like SemVer, the behavior specified is the Public API. When you are talking about code, the types and methods you expose for consumption by others is the Public API.

If you look at SemVer, the spec, the behavior is the API, and yes it follows its own rules.

In your example, you have a Code API. Behavior of a Code API is an implementation detail. The behavior of calling that API should be projected in the names of its members. I also do not see your example as a backwards incompatible change, since you are adding behavior. Personally I believe that naming methods correctly as to their intent helps eliminate these issues, and I would push back on a behavior change like this without changing the Code API, suggesting names like Create, Update, and CreateOrUpdate.

Again, if your save methods behavior went from create or update to only update, I would also assume that a create method was introduced, which would be reflected in a change to the Public API.

@EddieGarmon commented on GitHub (Jul 18, 2013): I think the understanding of what `Public API` is probably needs a FAQ entry. Generally for specifications, like SemVer, the behavior specified is the Public API. When you are talking about code, the types and methods you expose for consumption by others is the Public API. If you look at SemVer, the spec, the behavior is the API, and yes it follows its own rules. In your example, you have a Code API. Behavior of a Code API is an implementation detail. The behavior of calling that API should be projected in the names of its members. I also do not see your example as a backwards incompatible change, since you are adding behavior. Personally I believe that naming methods correctly as to their intent helps eliminate these issues, and I would push back on a behavior change like this without changing the Code API, suggesting names like Create, Update, and CreateOrUpdate. Again, if your `save` methods behavior went from `create or update` to only `update`, I would also assume that a `create` method was introduced, which would be reflected in a change to the Public API.

GiteaMirror commented

2026-04-25 16:43:54 -05:00

@mbaltaks commented on GitHub (Jul 24, 2013):

If you include the documentation of the API calls as part of the API, and more importantly the automated black box test cases also as part of the API, it might help decide how to handle this situation.

When the behaviour of a call changes, such as the save behaviour changing from update only to create and/or update, this would have to be followed by a change to the documentation, because the behaviour has now changed, even though the call signature has not changed. Also, the test cases that show how the original call failed when save was called on a non existent item will no longer pass, and so they need updating as well. Since the black box test cases for the original API no longer all pass, I'd call that an incompatible API change. That's just my opinion.

@mbaltaks commented on GitHub (Jul 24, 2013): If you include the documentation of the API calls as part of the API, and more importantly the automated black box test cases also as part of the API, it might help decide how to handle this situation. When the behaviour of a call changes, such as the `save` behaviour changing from `update` only to `create and/or update`, this would have to be followed by a change to the documentation, because the behaviour has now changed, even though the call signature has not changed. Also, the test cases that show how the original call failed when `save` was called on a non existent item will no longer pass, and so they need updating as well. Since the black box test cases for the original API no longer all pass, I'd call that an incompatible API change. That's just my opinion.

GiteaMirror commented

2026-04-25 16:43:55 -05:00

@FrVaBe commented on GitHub (Jul 24, 2013):

In the meantime I also think that public API includes the system behaviour in this document and not only the exposed programming interface. Thus I will close the issue. A FAQ entry about this would nevertheless be nice. Thanks everybody for clarification

@FrVaBe commented on GitHub (Jul 24, 2013): In the meantime I also think that `public API` includes the system behaviour in this document and not only the exposed programming interface. Thus I will close the issue. A FAQ entry about this would nevertheless be nice. Thanks everybody for clarification

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#2800