Please add a FAQ entry about platform support

[mvz]

I've been in several discussions about what to do about supported platforms (i.e., for Ruby gems, versions of Ruby, for npm packages, versions of node).

Here's a recent example: #708

I see two possible positions:

1. Semver is only about the documented API, so similar to updating dependencies, dropping supported platforms could even happen in a patch release.
2. Dropping a supported platform is a breaking change so that should only happen in a major release.

(I have a preference but that is not really relevant to this ticket!)

There is already an entry in the FAQ section about updating dependencies. Having one for platform support would help projects a lot in adhering to semver.

[ljharb]

Supported platforms are always part of the documented API. A FAQ entry would be nice but it doesn't change that that's how it works.

[mvz]

@ljharb this ticket is explicitly about a FAQ entry. I have not heard from anyone but you on this, and you have already indicated you can't make a FAQ entry happen. I'd like te see a response from someone who can.

[krader1961]

It seems to me pretty obvious that semantic versioning only applies to the public API. Dropping support for a platform does not change the public API. Doing so should not result in a bump of the major version. I don't think this warrants a FAQ entry but I have no objection to adding such a FAQ clarification.

[ljharb]

A breaking change is something that requires the consumer to make changes to their application after updating. Upgrading the platform version is included in this - dropping support for a platform is both obviously and objectively a breaking change.

[krader1961]

A breaking change is something that requires the consumer to make changes to their application after updating.

Obviously adding a platform is not a breaking change that warrants bumping the major number. Which is why removing a platform is not a breaking change. Anyone using a module on a platform that is no longer supported can simply pin their use to the last supported version. The project should ensure that if they do not do so their builds will fail. I don't think dropping support for a platform warrants bumping the major number.

[ljharb]

@krader1961 no, adding a platform is adding stuff, so it's a minor version. removal is typically major, addition is typically minor.

The platform's support status is irrelevant.

[krader1961]

@ljharb, I am ambivalent with respect to your argument. Please point us to where "Supported platforms are always part of the documented API" is itself documented. Even for a different project. A platform might be dropped for many reasons. Such as the platform no longer being actively maintained. Dropping support for that platform is not a breaking change for every other platform.

I understand why you are making your argument. If a project drops support for a platform its public API for that platform has, technically, changed. But no other platform is affected and the affected users of the, now unsupported, platform can simply pin their dependency. It is not at all obvious that dropping support for a platform warrants changing the major version since the reason for dropping support has nothing to do with changing the public API other than for that platform.

[ljharb]

“changing the API other than <changing the API for nonzero users>“

[07831968138]

F

[jwdonahue]

This is a perennial issue that arises out of the fact that the spec talks about API's more than packages AND it has a broad definition of what an API is:

1 Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it SHOULD be precise and comprehensive.

It turns out that in practice, we rarely ever actually version our Programming Interfaces (classic API's). Most of the SemVer implementing tools are in fact packaging tools, where the version string applies to an entire collection of interface/implementation code, data, binaries and metadata. The later normally includes something like a package manifest. The package manifests have come to be considered part of the public API, in many of these tool chains.

It's all about what exactly are you versioning? If it's a core set of function/method signatures in a header file, then implementation details regarding supported platforms would not be included, as literally specified by the SemVer spec. But the cases where arguments arise over breaking changes around supported platforms never arise in such pure API cases. They arise out of environments/tool-chains where the version string is applied to a package and its manifest, which tend to reference implementation details and dependencies.

[nVitius]

It sounds like the maintainers of semver have strong opinions on this one; I don't think discussing it further is really going to take us anywhere. This issue has gotten off-track though. To avoid further questions about how this should or should not work, can we please add an entry into the FAQ regarding this point of discussion?

[broofa]

Stirring the pot...

We (the uuid module maintainers) are dropping support for node 8 and IE 11 after uuid@8.3.2. Specifically, we're dropping those platforms from our CI testing matrix and, moving forward, will be closing issues specific to those platforms as "WON'T FIX". So how should this be reflected in the release version?

The answer is self-evident: It has to be a major release. The fact we no longer test legacy platforms means that when a legacy-breaking change gets introduced (probably in the form of some otherwise minor change), we are unlikely to know about it.

Thus, the only responsible option is to do a major version bump now, even if everything else in the API remains unchanged.

[ljharb]

@broofa indeed, that's a breaking change, so you'd need to bump to v9 (altho i'm sad about that decision)

[mvz]

@broofa you can certainly do that if you want, but semver as defined does not force you to do so.

[ljharb]

@mvz yes it does, because users on node 8 will see their code no longer work when they install the update, which the spec forces you to mark as a breaking change.