Allow major version to be zero

[jcornaz]

New feature motivation

Semantic-versioning allow to communicate that a software is in its initial development phase by having the major version of 0. Example: 0.3.1

This is very useful in order to start shipping very early a new software/library and gather as much feedback as possible as early as possible. Yet we don't want to miss-inform users. They must know from the version number that the software is in its initial development phase and that anything can change at any time.

See: https://semver.org/#spec-item-4

New feature description

When configuring the branch, asides the prerealease: Boolean option, there could be a initialRelease: Boolean (name can be improved)

In case you wonder, no prerelease and initialrelease are not mutualy exclusive:

prerelease	initialrelease	version
true	true	0.1.0-beta.1
false	true	0.1.0
true	false	1.0.0-beta.1
false	false	1.0.0

[gr2m]

version numbers are for machines, not people. They are a contract between a library and its dependents. I'd strongly recommend to start at version 1.0.0, just like npm does when you use npm init by default.

You can create pre-releases as you suggest (1.0.0-beta.1, etc). And if you want users to know that your software is not yet complete, I would recommend to state so in the projects README

I don't see a need for yet another flag.

[jcornaz]

I'd strongly recommend to start at version 1.0.0

Thanks for your recommendation. I however would like to follow semantic-versioning recommendation.

This tool is named "semantic-release" wouldn't it be nice if it supported semantic versioning?

At least maybe it could be documented that semantic versioning is not fully supported and why. That would have saved me hours of looking in the doc for the feature.

[gr2m]

The meaning of 0.x version is not clearly defined/understood.

I agree could document that fact somewhere, if we haven't yet. I'm sorry you spent so much time because of this :(

[travi]

there is an FAQ about this in the documentation: https://semantic-release.gitbook.io/semantic-release/support/faq#can-i-set-the-initial-release-version-of-my-package-to-0-0-1

[jcornaz]

Thanks @travi for pointing the FAQ!

[travi]

sure thing. i think the reasons linked from there are helpful and align with what @gr2m mentions above. i had similar hesitations early on, but have come around to agree. especially since semantic-release supports pre-releases so well now, i think that is the best recommendation.

[jcornaz]

sure thing. i think the reasons linked from there are helpful and align with what @gr2m mentions above. i had similar hesitations early on, but have come around to agree. especially since semantic-release supports pre-releases so well now, i think that is the best recommendation.

I am not sure yet.

For instance this is is not a breaking change: 0.1.0 -> 0.1.1
But this is a breaking change: 1.0.0-alpha.1 -> 1.0.0-alpha.2

So without the major version 0, I have no way to publish a version and inform the users if the change is breaking or not, when I want to still be explicit that the overall API is under construction.

[travi]

my recommendation is to limit the amount of time that you use a pre-release and try to get to v1.0.0 as early as you can 1.4.6 -> 2.0.0 communicates the breaking change much more clearly than 0.1.0 => 0.2.0 since not all consumers understand the latter and many tools don't support it properly.

as @gr2m highlighted, semver is for machines. it communicates things like breaking changes. its ok to publish v1.0.0 once the package has a minimum functional use case and publish v2.0.0 as soon as the api breaks. if you follow semver properly targeting machines, you will have far more major versions than when trying to hold things back and tie major versions to marketing type releases.

if you are still concerned about stability, use pre-releases some more after you've promoted v1.0.0 to no longer be pre-release so that you then have multiple channels (@latest and whatever you are publishing the new pre-releases to, like @alpha or `@beta). i think the use of channels communicates stability better than v0 anyway.

[jcornaz]

1.4.6 -> 2.0.0 communicates the breaking change much more clearly than 0.1.0 => 0.2.0

I completely agree.

But 1.0.0 does not communicate well the "this is a very new and under construction API"...

I am especially afraid that after publishing 1.0.0, some people start to use the library and get pissed off when the version 2.0.0 is released one month later.

Reciprocally as soon as the version 1.0.0 is released I'll feel obliged to break the API only when I really really have to. But the thing is, I also want the API to be as good as possible, and to achieve that, at the beginning, I'd need to do some small breaking changes in order to improve usage of the API.

Probably all the disagreement come from the fact that you think version numbers are for machines, where I am convinced that they are important to communicate to humans as well (otherwise why would we need prereleases for?). I always consider the version number of a library before adopting it. I will make sure I am ready to migrate a lot of code before adopting a library published as 0.y.z And I will abandon quickly libraries that do not follow semantic versioning or that published as 1.0.0 an API which is still unstable.

You talk about marketing releases. But I think realeasing as 0.y.z is just being honest with the users, saying loud and clear: "The API is still under construction"

Nevertheless, thank you guys for the feedback. I admit, I didn't expect that answer, and it gave matter to think about.

[jcornaz]

@gr2m, @travi, Since that FAQ states "it's not considered a good practice", could it provide sources about that?

Right now, the links provided by the FAQ are:

• a blog post that indeed seems to be written by someone who doesn't like 0.y.z versions
• the semantic versioning specification that says to start version at 0.1.0
  • By the way, the title of the FAQ is incorrect, semantic versioning starts at 0.1.0, not 0.0.1
  • And fun fact, even semantic versioning specification itself started at 0.1.0: https://semver.org/spec/v0.1.0.html

Unless other sources are provided, I don't see a reason to favor a random blog post over an official specification.

Could you maybe provide more sources of your statement? Or maybe reword the FAQ answer, so that we understand that it is an opinionated point of view that semantic-release takes?

And of course, don't forget to remove the link to the semantic versioning specification in that FAQ. Since it says the opposite, it only adds to the confusion ;-)

[simonihmig]

At least maybe it could be documented that semantic versioning is not fully supported and why. That would have saved me hours of looking in the doc for the feature.

Same here! Just stumbled upon this issue when looking for a solution to publish 0.x versions.

I agree with the points @jcornaz made. And I want to specifically add that being so opinionated about the versioning in this case seems not to be a good choice for a tool, the user should be able to have the final word here. Whether it's the more philosophical question whether versions are for machines or humans (I think it's both) or the concrete case of supporting 0.x releases (which are so widely used in the eco system, and again part of SemVer specs).

Btw, with previous 0.x releases published, semantic-release does seem to work with 0.x versions, however not exactly in the way the common conventions are (based on the way ^ works):

• increase the minor version for breaking changes (0.1.2 -> 0.2.0)
• increase the patch version for features/fixes (0.1.2 -> 0.1.3)

Not sure I will be able to use it with the current limitations...

[dcodeIO]

I'd also be interested in staying in the v0.x.x version range. Some context in the issue linked above. Essentially we have decided to indicate that our TS to Wasm compiler isn't quite ready to be perceived as being something finished, because the underlying tech isn't, so we'd prefer to keep the version below a v1 while critical language features are still in the works. That doesn't imply that it isn't useful for folks already, but prereleases as recommended on the docs don't quite cut it.

Currently investigating if a fork pinning the version below v1 in the way we'd expect is an option, but we'd certainly prefer official support for this. What I'm imagining there is an option --prev1 or similar enabling the behavior, and one would remove it once a project is ready for a v1.

[jcornaz]

I reopen this issue, since there is obviously an action that must be done.

Option 1:

Add support for 0.y.z versions. Again, this is part of the semantic versioning specification. Therefore it does make sense to be supported by a tool named "semantic-release". Whether or not to publish a 0.y.z version is a decision that the user should be able to make.

Option 2:

Update the documentation. The current FAQ entry is confusing, because it points to the semantic versioning specification for more details. But it turns out that the semantic versioning spec does recommend to start initial development at 0.1.0.

If you really do not want to support 0.y.z, you should be transparent on the fact that it is an opinionated and conscious divergence from the actual semver specification.

[gr2m]

We talked once more about the topic, but our conclusion remains that this is much more complicated than it looks. Adding this feature will likely create lots of more issues, and we are having a hard time supporting semantic-release as is today.

Sorry :(

We will not be implementing it in semantic-release. And we have an alternative solution that is supported today: using pre-release channels, see https://semantic-release.gitbook.io/semantic-release/support/faq#can-i-set-the-initial-release-version-of-my-package-to-0-0-1

[jcornaz]

@gr2m

Ok. Thanks for the update. I'm of course sad to see that outcome.

Nevertheless can you clarify the documentation please?

As I was saying:

The current FAQ entry is confusing, because it points to the semantic versioning specification for more details. But it turns out that the semantic versioning spec does recommend to start initial development at 0.1.0.

If you really do not want to support 0.y.z, you should be transparent on the fact that it is an opinionated and conscious divergence from the actual semver specification.

[jcornaz]

especially since semantic-release supports pre-releases so well

And we have an alternative solution that is supported today: using pre-release channels

@gr2m, @travi, just so that you know, using pre-releases is not always an option. For rust projects it is established and documented convention (by the rust team) that a rust crate with unstable public dependencies should have a major version number 0. And since so many libraries have a major version 0 in the rust ecosystem, semantic-release simply cannot be used for many rust projects. 😢

[deviprsd]

@jaketrent There is work around, but it requires first publishing at 0.x using npm and then adding in semantic-release. We have done it internally at work, but its a little hectic to get setup the first time

[jcornaz]

There is work around, but it requires first publishing at 0.x using npm and then adding in semantic-release

As far as I am aware, that will not work. When releasing a feature, semantic-release will bump from 0.1.0 to 0.2.0 (it should bump to 0.1.1 instead). And when releasing a breaking change it will bump to from 0.1.0 to 1.0.0 (it should bump to 0.2.0 instead).

[zaquestion]

I'd be much happier with this tool and find it more intuitive to use if it just supported v0.1 as the initial release and bumped the versions using the same rules as >0. Then when I'm ready to make a public (stable) release I can trigger a major version bump.

At work we use this tool for everything, and as a result no service or library that our developers create is ready/usable at 1.0.0. Using prereleases would mitigate this, but have wide sweeping impacts on our dev tooling and workflows. Supporting major version 0, would allow business to flow as usual and developers to choose when to explicitly make the v1 bump. Other less than great work arounds have cropped up as well such as making every commit chore: until ready to make a proper release, but these muddies the commit history and makes it difficult to get clients pushed out ahead of a service being implemented and stood up.

[trallnag]

Release Please by Google supports this use case so it could be used as an alternative

[benkeil]

what a bullshit decision. the prerelease feature understand absolutely nobody on the world. if this is your workaround than document it proper.

and why do you believe you can decide how I want to release my stuff for internal use???

how the hell should this work?

{
  "branches": [
    "main",
    {
      "name": "feat/*",
      "prerelease": true,
      "channel": "beta"
    }
  ]
}

[MatteoGioioso]

Release Please by Google supports this use case so it could be used as an alternative

As well as svu: https://github.com/caarlos0/svu, though a bit more piping is needed, but it is very light weight and it starts from 0.0.0

[tkornuta-getgenai]

The meaning of 0.x version is not clearly defined/understood.

I agree could document that fact somewhere, if we haven't yet. I'm sorry you spent so much time because of this :(

What do you mean "not clearly defined/understood"?

It's perfectly defined here: https://semver.org/#spec-item-4

"Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable."

[tkornuta-getgenai]

what a bullshit decision. the prerelease feature understand absolutely nobody on the world. if this is your workaround than document it proper.

and why do you believe you can decide how I want to release my stuff for internal use???

how the hell should this work?

{
  "branches": [
    "main",
    {
      "name": "feat/*",
      "prerelease": true,
      "channel": "beta"
    }
  ]
}

Hey @benkeil I agree with you, this is just mind-blowing that the tool that at first eye sight is the prime promoter of semantic versioning does such a weird twist. The worst is that I've already invested some of my time into integrating it into my workflow 😞

I am working on an app that has backend (python) and frontend (js/react), in both I want to use semantic releases.
And funny fact: the python semantic release is "derivative" of this project...! 🤯
https://github.com/python-semantic-release/python-semantic-release

Both are initial devs and now, due this tiny detail, my frontend is 1.x.y and backend is 0.z.w... This - honestly - makes me anxious!

@benkeil have you found other semantic release tools for react/js that deal with this in a proper way? thx

[gr2m]

what a bullshit decision

Please be kind. It's okay to be upset, but this is not how we communicate.

We are firm on our decision. We thought more about versioning than probably most of you. It's much easier to get over applying some deeper meaning to version numbers than a contract of compatibility. There is nothing magical about a 1.0.0. If the APIs are still unstable then you release breaking versions until they are. If you consider your APIs stable at 7.0.0 then so be it, it doesn't matter, it's nothing but a number.