[GH-ISSUE #874] increment the MAJOR version when you make incompatible ... changes #2297

New Issue

GiteaMirror · 2026-04-20T10:18:14-05:00

GiteaMirror commented

2026-04-20 10:18:14 -05:00

Originally created by @bitbonk on GitHub (Sep 15, 2022).
Original GitHub issue: https://github.com/semver/semver/issues/874

The spec says right at the beginning

increment the MAJOR version when you make incompatible API changes

but what about incompatible changes that does change the API surface, e.g. when you only make incompatible behavioral changes?

Originally created by @bitbonk on GitHub (Sep 15, 2022). Original GitHub issue: https://github.com/semver/semver/issues/874 The [spec](https://semver.org/) says right at the beginning > increment the MAJOR version when you make incompatible API changes but what about incompatible changes that does change the API surface, e.g. when you only make incompatible behavioral changes?

GiteaMirror closed this issue

2026-04-20 10:18:15 -05:00

GiteaMirror commented

2026-04-20 10:18:16 -05:00

@ljharb commented on GitHub (Sep 15, 2022):

the API includes all of the behavior, not just the interface.

@ljharb commented on GitHub (Sep 15, 2022): the API includes all of the behavior, not just the interface.

GiteaMirror commented

2026-04-20 10:18:16 -05:00

@bitbonk commented on GitHub (Sep 15, 2022):

Shouldn't the spec be more clear about this? I am pretty sure that most people associate the interface when they read "API" (application interface).

@bitbonk commented on GitHub (Sep 15, 2022): Shouldn't the spec be more clear about this? I am pretty sure that most people associate the interface when they read "API" (application _interface_).

GiteaMirror commented

2026-04-20 10:18:16 -05:00

@ljharb commented on GitHub (Sep 15, 2022):

Yes, it probably should. The problem is that most people think "interface" in programming means "your function signatures and types", it actually means "any way you interact with it", which encompasses all observable behaviors and properties.

@ljharb commented on GitHub (Sep 15, 2022): Yes, it probably should. The problem is that most people think "interface" in programming means "your function signatures and types", it actually means "any way you interact with it", which encompasses all observable behaviors and properties.

GiteaMirror commented

2026-04-20 10:18:17 -05:00

@jwdonahue commented on GitHub (Sep 16, 2022):

The correct answer is it depends on what you are versioning. If you are versioning the interface, then any implementation details are not your concern. If you are versioning both the interface AND implementation, as-in, you're probably versioning a package, then major version bump if you make a breaking change to either the interface or the implementation. In fact, some package format changes, unrelated to your code, can be considered to be breaking changes if they break somebody's build system.

This does not apply to bugs that are mistakenly taken to be intended behavior. If your documentation says f() turns the lights on, but you have a bug that causes flickering, or the wrong color of light is emitted, per your docs, you can fix that with a patch level bump and ignore anyone who screams that they were dependent on that errant behavior. In other words, "all observable behaviors and properties" are not necessarily part of the interface, unless you make that claim in your documentation.

The spec literally states that you define what "API" means in the context of your code.

@jwdonahue commented on GitHub (Sep 16, 2022): The correct answer is it depends on what you are versioning. If you are versioning the interface, then any implementation details are not your concern. If you are versioning both the interface AND implementation, as-in, you're probably versioning a package, then major version bump if you make a breaking change to either the interface or the implementation. In fact, some package format changes, unrelated to your code, can be considered to be breaking changes if they break somebody's build system. This does not apply to bugs that are mistakenly taken to be intended behavior. If your documentation says f() turns the lights on, but you have a bug that causes flickering, or the wrong color of light is emitted, per your docs, you can fix that with a patch level bump and ignore anyone who screams that they were dependent on that errant behavior. In other words, "all observable behaviors and properties" are not necessarily part of the interface, unless you make that claim in your documentation. The spec literally states that you define what "API" means in the context of your code.

GiteaMirror commented

2026-04-20 10:18:17 -05:00

@bitbonk commented on GitHub (Sep 16, 2022):

That makes perfect sense, thank you!

@bitbonk commented on GitHub (Sep 16, 2022): That makes perfect sense, thank you!

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#2297