Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Clarify points 4 and 5 in Semver 2.0 #490
Many people seem to be having semantic arguments over points 4 and 5. Specifically, when should the API be considered "released for the public", or when is it best to define version 1.0.0?
I've had numerous conversations in which a project that is pre 1.0 but is already released for public consumption. I personally believe that this project is not using Semver correctly (per the intent of Semver), because it's a public API which should be at 1.0.0. Their argument is that the project is using it correctly because it's pre 1.0 and they're allowed to break the API at any time, even though it's already released for wide public use.
I believe the intent is that anything pre 1.0 is considered "beta" software, and is not intended to be used in production environments, or used by large organizations that have a requirement of stability. However, people assume that a project can choose to never use the 1.0.0 version number and get away with any sort of breaking changes, even after releasing the code to the public, documenting the API, and gaining a following of users.
This is how I would change the text to avoid confusion and semantic arguments regarding when and how to use pre-1.0 and post-1.0 version numbers.
You seem to have specified several goals here and I am curious as to which one is the main or "true" goal. Are you looking to stop people debating over points 4 and 5? Are you looking to change projects which are in your opinion abusing this feature of semver, so that they release major versions? Are you looking to get fewer people using projects at version 0.y.z by indicating that they are not "public"? Are you thinking about this from a package-maintenance context like the semver maintainers are ("when is it safe to upgrade a package? never, if the first digit is 0.") or from some sort of other context, and what is that other context? I'd like to understand your needs better as I think anyone saying "this project implements semver" probably means that aspirationally rather than explicitly; they probably have shipped a breaking change with only a minor bump out of ignorance about some circumstance which is broken.
I'd also like to call attention to something of a larger question here, and it's along the lines of xkcd's "Workflow" comic: what I like about semver is that it makes some sort of oblique reference to a specification for how the software should work. One would want the specification to say that version 1.0.0 should be released when this specification has stabilized. Once we open dialog about specifications we start to talk about a sort of semver "formal semantics." And the reason that I'd be interested there, has to do with versioning something that is not explicitly depended upon by other software. For example, how might you apply semver to an app, or a game? Is a texture update "minor" or "major"?
So, what can we say about the formal semantics?
Just my two cents -- this very much only concerns the first bullet point but I see this question in that more specific context where one is trying to be clear enough to say what I think you want to say: "projects SHOULD release a version 1.0.0 as soon as there is any 'request' which should not be considered an error."