they point at my project version, which could be v7, v28, v33, and then say "This project versioning is bad." or "This project API is unstable."
Personally I'd stop listening to those people. They obviously still put some kind of cargo cult significance to versions and aren't making decisions on objective criteria.
That said, some of those version numbers are a bit excessive. That last one has had 33 major versions over 7 years; that is just about 5 major versions a year. I don't know the exact circumstances of that project, but that many breaking changes is in the ballpark of being unstable, in my opinion.
If you're changing the public api of your project that often, then you might want to consider longer design phase, so the api can be solidified before it's put into code; or if that isn't possible, maybe consider a longer pre-release/release-candidate stage so the official api can be worked out through use without affecting the major version number. Having a higher version number doesn't mean anything, but if I have to fixing breaking changes nearly half a dozen times a year, I might get upset over that.
Here is the thing: any change that may break someone's project by merely upgrading your dependency is a breaking change and requires that you bump the major version.
Maybe this is the confusion. That isn't at all the rule for major version bumps. The rule is Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. None of the items in your list are changes to the public api, except maybe the forth one about changing a type definition.
To go through them. Forgive me if some details are off, web frameworked projects aren't my main areas.
Changing the version of the supported platform isn't a breaking change, because it doesn't change the public api. To use conventional commits terms, it is a build type change, not an api type change.
Tests aren't part of the public api, so changes to them are test type changes, not api type changes, therefor they aren't breaking, regardless of what implications that has about what the main library does or doesn't support.
Fixing a bug is only a breaking change if it changes the public api. Even if people use the erroneous behavior, if fixing it doesn't require a public api change, then it isn't a breaking change.
If the type is part of the public api and you change that types definition, then, yea, that's a breaking change and will require a major version bump.
Updating dependencies is a build type change and is only breaking if changes in their api forces changes in your api. Otherwise, not an api or breaking change.
This has nothing to do with any stigmas about versions. The semver spec is clear enough that it is entirely concerned with the public api of a project, how that public api changes, and how those changes affect the version number. That's it, nothing more or less.
The two relevant quotes I can find in the the spec both say the same thing.
From the introduction:
Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.
From the actual spec rules:
8. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API
Of course, use version numbers however you want, but semver is very clear; it doesn't care if your update breaks other projects, it only cares if you break the public api.
MUST be incremented if any backwards incompatible changes are introduced to the public API. None of the items in your list are changes to the public api, except maybe the forth one about changing a type definition.
All of the changes that I've listed introduce backwards non-compatible changes, e.g.
dropping Node.js version support
While whatever I typed in the codebase may not change the API as it appears in the source code, the transpiled version of the code now includes API changes that are no longer incompatible with my program, i.e. If you were running a jay-keckel-app that depends on my package slonik@28.0.0 and upgraded to slonik@28.1.0 you would most certainly not expect that to break your app, and if dropping platform version is not considered a breaking change, then it most certainly will. It is that simple.
To use conventional commits terms, it is a build type change, not an api type change.
This would be true only if JavaScript was a compiled language.
Tests aren't part of the public api
They are part of the contract that guarantees the integrity of the API, i.e. If tests are not passing on the platform for which the package was released originally, that's a breaking change.
Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API
FYI, we are not the first to have this debate. There is a long, ongoing debate in the semver repository on exactly this subject.
All of the changes that I've listed introduce backwards non-compatible changes
Sure, but they don't all introduce public api changes and that's the point, semver only speaks to the public api.
While whatever I typed in the codebase may not change the API as it appears in the source code, the transpiled version of the code now includes API changes
Ah, as I said, node/javascript ecosystem is not my main area of expertise, so fair enough, my bad.
They are part of the contract that guarantees the integrity of the API
Ok, but that isn't the same thing as being part of the public api.
FYI, we are not the first to have this debate. There is a long, ongoing debate in the semver repository on exactly this subject.
Thanks for the link, it's an interesting debate, but it's ultimately moot. The spec says what the spec says and no where does the spec mention supported platforms being part of the public api, so it isn't part of the public api. Maybe that will change in semver 3.0.0, but as it stands, it is what it is or isn't what it isn't, as the case may be.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Personally I'd stop listening to those people. They obviously still put some kind of cargo cult significance to versions and aren't making decisions on objective criteria.
That said, some of those version numbers are a bit excessive. That last one has had 33 major versions over 7 years; that is just about 5 major versions a year. I don't know the exact circumstances of that project, but that many breaking changes is in the ballpark of being unstable, in my opinion.
If you're changing the public api of your project that often, then you might want to consider longer design phase, so the api can be solidified before it's put into code; or if that isn't possible, maybe consider a longer pre-release/release-candidate stage so the official api can be worked out through use without affecting the major version number. Having a higher version number doesn't mean anything, but if I have to fixing breaking changes nearly half a dozen times a year, I might get upset over that.
Maybe this is the confusion. That isn't at all the rule for major version bumps. The rule is
Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. None of the items in your list are changes to the public api, except maybe the forth one about changing a type definition.To go through them. Forgive me if some details are off, web frameworked projects aren't my main areas.
Changing the version of the supported platform isn't a breaking change, because it doesn't change the public api. To use conventional commits terms, it is a build type change, not an api type change.
Tests aren't part of the public api, so changes to them are test type changes, not api type changes, therefor they aren't breaking, regardless of what implications that has about what the main library does or doesn't support.
Fixing a bug is only a breaking change if it changes the public api. Even if people use the erroneous behavior, if fixing it doesn't require a public api change, then it isn't a breaking change.
If the type is part of the public api and you change that types definition, then, yea, that's a breaking change and will require a major version bump.
Updating dependencies is a build type change and is only breaking if changes in their api forces changes in your api. Otherwise, not an api or breaking change.
This has nothing to do with any stigmas about versions. The semver spec is clear enough that it is entirely concerned with the public api of a project, how that public api changes, and how those changes affect the version number. That's it, nothing more or less.
The two relevant quotes I can find in the the spec both say the same thing.
From the introduction:
From the actual spec rules:
Of course, use version numbers however you want, but semver is very clear; it doesn't care if your update breaks other projects, it only cares if you break the public api.
All of the changes that I've listed introduce backwards non-compatible changes, e.g.
While whatever I typed in the codebase may not change the API as it appears in the source code, the transpiled version of the code now includes API changes that are no longer incompatible with my program, i.e. If you were running a
jay-keckel-appthat depends on my packageslonik@28.0.0and upgraded toslonik@28.1.0you would most certainly not expect that to break your app, and if dropping platform version is not considered a breaking change, then it most certainly will. It is that simple.This would be true only if JavaScript was a compiled language.
They are part of the contract that guarantees the integrity of the API, i.e. If tests are not passing on the platform for which the package was released originally, that's a breaking change.
FYI, we are not the first to have this debate. There is a long, ongoing debate in the semver repository on exactly this subject.
github.com/semver/semver/issues/716
Sure, but they don't all introduce public api changes and that's the point, semver only speaks to the public api.
Ah, as I said, node/javascript ecosystem is not my main area of expertise, so fair enough, my bad.
Ok, but that isn't the same thing as being part of the public api.
Thanks for the link, it's an interesting debate, but it's ultimately moot. The spec says what the spec says and no where does the spec mention supported platforms being part of the public api, so it isn't part of the public api. Maybe that will change in semver 3.0.0, but as it stands, it is what it is or isn't what it isn't, as the case may be.