Let’s Be Honest — v0 is not SemVer
Better sequential versioning for A̵P̵I̵s̵ products.
{Versioning} ⊇ {Sequential Ver} ⊇ {Semantic Ver}
Versioning is as old as software itself, but Semantic Versioning (aka SemVer) is a recent invention. Before SemVer, marketing (along with other stakeholders in a project) would subjectively determine how software version numbers got incremented. With SemVer, version numbers are meant to convey well-defined facts about the objective state of the code. SemVer has very little to do with the subjective state of the code or the product. Going from version N to version (N+1) doesn’t mean that the code is improving or becoming more stable. There’s no implicit signaling that version (N+1) is more stable than version N; it means the exact opposite.
If an API is published and has users who are not part of the internal team, then that API is public and no longer in v0. Don’t let the inner perfectionist or marketing tell you otherwise. Automated tooling that keeps SemVer[ed] dependencies up to date do so to quickly pick up minor updates with performance improvements, bug fixes, and most importantly, patches for security vulnerabilities.
If an API is published and has users who are not part of the internal team, then that API is public and no longer in v0.
When project releases don’t follow the SemVer (Spec #8) MUST INCREMENT and yet project releases are marketed as SemVer, the software is a liability. Downstream dependents using automated infrastructure (e.g., dependabot) will end up breaking while trying to automatically (and responsibly) patch a security vulnerability, for example. Within the context of numerical applications, such a consequence has serious implications. It makes things more difficult for researchers by hindering reproducibility and harms businesses by creating unexplained quantitative differences.
Blame it on the Google
It was Google that made the connotation of “beta” more of a marketing term (watering down the technical definition) as they released a gobble of different web apps and services in the early 2000s. The big difference from many of today’s “beta” releases is that those early “beta” web apps often didn’t expose programmatic APIs. There was no such thing as “breaking change” or “backward compatibility.” To many, “beta” meant “new,” which had its appeal in the age of free services powered by advertising dollars.
Apps often prominently displayed the term in their logos to leverage that novelty factor. But mostly the term “beta” meant the product could be discontinued if it didn’t move to a v1. Therefore the transition to v1 meant “success” and represented a unique marketing opportunity. That’s simply textbook sequential versioning.
Archimedean P̵r̵o̵p̵e̵r̵t̵y̵ Guess
Naturally, v0 necessarily comes before v1. That’s possibly how “beta” came to manifest itself as v0 when apps and libraries started exposing sequentially versioned “beta” programmatic APIs. When Node.js, NPM et al. made semantic versioning à la mode, many projects jumped on the bandwagon with their existing v0 sequential designation but avoided changing their release proccess. It’s as if sequential versioning became too embarrassing and everyone started faking SemVer.
If you create a new npm package (e.g., npm-init) to be published on the registry, the SemVer is 1.0.0.
It’s also important to keep in mind that popular usage of the term “beta” and its v0 manifestation predates SemVer, and SemVer is a subset of sequential versioning. If a project is using v0 and making breaking changes without bumping the major version number, then the project is not using a “modified flavor of SemVer” — it’s using basic sequential versioning.
To denote the maturity or the subjective state of a specific release, it’s best to use a SemVer (Spec #9) Identifier (e.g., 1.3.20-beta). The “beta” label communicates to humans whereas the SemVer number communicates to computers.
Next [Sem] Generation Versioning
As for a sequence that carries the same political, emotional, or marketing connotations of transitioning from “version 0 to version 1”, consider the construct of Semantic Generation versioning (aka SemGen).
The SemGen (e.g., “generation x release”) of a software is a subjectively determined sequence of major-minor SemVers.
It can be included in the release metadata (or logo) and is subjectively defined for marketing or non-technical purposes without overloading the strict technical definition of SemVer.
This construct is being considered for the NumFOCUS-sponsored Econ-ARK project as we encounter rapid adoption while simultaneously iterating on user feedback and making major architectural changes.
The goal is avoiding a situation where the library is in SemVer-zero with thousands of users, making it more difficult (for everyone) to safely upgrade as we continue to improve.
Without proper SemVer, a project loses the ability to effectively backport minor-version API deprecation warnings and breaking changes have to be manually communicated and painstakingly discovered at runtime.
