Starting with semver `1.0.0`

Look I get it. You're releasing a new package... stepping out, uncertain if the library will need changes. So you say, "maybe I should release v0 now and release v1 later when it's ready enough". This article will attempt to persuade you to release v1 from the beginning.

There are a few reasons to release v1:

• SemVer 0.x versions are different
• be confident and take it seriously
• project strength

To me, it seems that the various reasons for v0 boil down to:

• uncertainty
• laziness
• lack of understanding / skill issue

...

But after reading this interesting Issue on the semver repo: https://github.com/semver/semver/issues/221 my opinion is changing. Using version 0.x indicates instability, true, but the reality is that some libraries are unstable.

What do I mean by unstable? It's not that the library changes (because those changes can be planned and be represented by major version numbers). Instability relates to the prevalence of bugs.

Bugs may be:

• regular software bugs, or
• breaking changes released in a minor or patch versions.

Side note: there's little difference between these two. A lot of bugs are just mismatches or incompatibilities between APIs.

So --- how likely is it that your library will break for consumers? Only library maintainers can answer this question, and it's often sourced from experience with issues that have been brought up over time by your consumers.

But how do you know how unstable the library will be before you release it? Maybe a period of time in 0.x is a good idea.

But will the library ever get out of 0.x? Because inertia is a real thing. Will you have time? Will it pass the committee? That's a risk.

On the other hand, the risk of releasing 1.0.0 is that consumers will get instability if they upgrade frequently. But there are mitigations to this. Firstly, with lockfiles, upgrading packages is a manual action. Consumers are not affected by issues unless they upgrade. And they can simply not upgrade, or defer the upgrade until later.

New consumers may land on a buggy release, that's true, but that would be the case in the 0.x system also.

Libraries like storybook are not very stable between versions (in my experience), yet they're still not using 0.x. For what it's worth.

And then there is the area of transitive dependencies. If your package is a dependency of another package, then that other package needs to decide what semver range to use. Your stability affects that package's stability, so the stakes are higher.

Either that package pins your library or uses a broader semver range. In the first case, it causes duplication which is bad for performance. In the second case it risks instability. I'd wager to say that the first option is a non-starter and instability is always a risk.

I don't have an answer here, but the main point is that if your library is used by other libraries then the stakes are higher and you should probably make sure your library is stable.

So you should try to write a stable library, but if it's unstable then go ahead and use 0.x until it's stable. But if you can, use 1.x.