Convention: how to get from 0.0.0 to 1.0.0

[AloisMahdal]

This is an extension to SemVer aiming to provide versioning scheme for project in their early states that could be described as "experimental", "ad-hoc" or "incubator". That is, this extension only deals with "0.y.z" versions.

Use case

There is an itch that you have which could be scratched by a tool that you would like to create and eventually proceed with development. Simply creating repo and adding some code would work, but if you are like me, you also want these things right from the start:

• Ability to create a distributable (and upgradeable) build whenever you want. Also ability to set up and use a CI-like system right away.

• Assign a version to your project -- obviously SemVer-compatible version in 0.y.z range.

• Have at least some "tongue-in-cheek" semantics to that version.

• Make it possible to eventually approach version "1.y.z". On the way there, already start to get used to applying SenVer's gating principles. The point being, as you are shaping your codebase, you also want keep testing its ability to support proper gating.

The good news is that you don't need to think up a detailed plan, there is already a meaningful and simple one:

Convention

1. First assign version 0.0.0.

   Nothing has to work or even exist.

   Although you already may want to set up things like CI, build system or some simple branching scheme.

2. At some point you proceed to 0.0.z.

   But in this phase it really means "0.0.MAJOR". Ie. things are generally expected to work
   but anything can break with any upgrade.

3. As you feel a bit more confident, you proceed to 0.y.z.

   But in this phase it really means "0.MAJOR.MINOR".

   This is when you first start to apply SemVer principles: you are still in the "privileged" 0.y.z range, but you already start to distinguish between breaking and non-breaking changes.

4. Eventually, you want to get serious so you release the glorious 1.0.0.

   Congratulations!

Notes

It's up to the author if they want to define more detailed expectations for each phase; however it is preferred to be done in the first (0.0.0) phase.

[yegeniy]

Love it, there's something special about version 1 of an API in an early stage of an application's development, which denotes stability.

That's exactly how I version projects with a small number of early users.
Technically, semver seems to recommend these kind of releases be treated as pre-release candidates, but it's much simpler to convey meaning with just the x.y.z format.
Early users generally care about additional features, not the nuances of semver compatibility.
Once adoption has grown or the API has been figured out, I re-release the last version of 0.Y.Z as 1.0.0, notify users that the two are equal, and that we are adopting semver going forward.

@AloisMahdal, is this a fair summary?

Until an app is at version 1.0.0:

• patches are released as an increment to z in 0.y.z.
• new features are released as an increment to either y or z in 0.y.z.
• Breaking changes are released as an increment to y in 0.y.z.
• Once adoption has grown or the API has been figured out, start using semver going forward by re-releasing 1.0.0.

[yegeniy]

(edited the above)

[AloisMahdal]

@yegeniy I'd say it's fair summary of point 3 and 4 in my original post. I provided also the "x=y=z=0" phase (1), which is "figure out and test the plumbing", and also the "0.0.z" phase (2) which is "run fast & break things while you can".

That said, the convention is not meant to be prescriptive, people are expected to fill in the gaps.

[elypter]

i would go with something more strict

0.0.0 should be a proposal (an informal version that could just be something like a forum post that is no set until 0.0.1. changes can be made without bumping the version)
0.0.1 the version when actual work starts but no code is there to test yet (setting up the environment or collecting data, creating a readme or picking a license)
0.0.X should be drafts and preparations without runable code
0.1.X should be anything that runs but isnt capable of doing anything useful.
0.X.X should be experimental implementations with varying levels of usefulness

a project doesnt have to start with 0.0.0 or even 0.0.X and most probably wont. its more of a placeholder and for people who really want to start organizing things early.

[AloisMahdal]

@elypter. as I understand your extension, it adds further milestones, but IMO the increase in complexity (and therefore burden for adoption) is not justified with any benefits.

Remember that versions are meant to communicate changes in code/interfaces, but in your extension there's "proposal" step using up 0.0.0 and another two steps burning through whole 0.0.y space, but neither of these actually have any code to communicate changes in. Also your description of 0.1.x fits into 0.x.x; again there's no real use in the distinction.

In the original version, the idea is to get some versioning and gating in place ASAP (0.0.0), and actually start producing testable code (0.0.1 and above).

[elypter]

my original motivation was that i find it rather unintuitive to start real versioning with 0. people are used to count from 1. 0.X.X is an exception but it is intended because its special meaning is that its a "pre"version, before the real counting begins. 0.0.0 is also different from for example 5.0.0 because it is interpreted as plain version 5 with no further additions or patches. 0.0.0 has nothing to refer to. it would mean no additions to nothing. so my idea was that 0.0.X and 0.0.0 should either not be allowed or have a special meaning. maybe its better to just define that versioning should start with 0.1.0 and let people use lower versions at their own responsibility.

[AloisMahdal]

"it would mean no additions to nothing" -- that's pretty much what I mean. It's not really meant to be any useful version info; it's really just for cases when you want to deploy and test some meta-data and scripts; not to label a release. The intuition that such version would feel weird if seen "in wild" is correct; 0.0.0 should never see the light of the world.

The overarching idea here is that 1.0.0 should signal some commitment at least to basic architecture, but some people (like me) are creative and like to change things heavily as they use them, while not to able to commit to the development fully (hobby project), so there can be dilemma of when (whether even) to publish the project and when to really reach 1.0.0. The solution is to provide semantic for 0.y.z and 0.0.z that can be used for extensive periods of incubation and alpha testing, so that people can slowly bring themselves to that commitment without losing the advantage of getting feedback. (Eg. I have at least 4-5 projects that have been in 0.y.z or even 0.0.z for years, and probably will stay like that for yet some time.)

Also note that the "special meaning" of 0 is already suggested in SemVer. Oh and also: sure, people are not used to count from 0, well, unless they happen to be software engineers. ;-)

[jwdonahue]

@AloisMahdal, this is mildly interesting and seems to even be a best practice at this point, but it doesn't really require any changes to the SemVer spec does it? Given that clause #4 reads:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Everyone is free to document whatever processes they intend to use and they all are all covered by the spec.

Unless you have questions or intend to follow up with PR, please close this issue at your earliest possible convenience.

[ioquatix]

Just my 2 cents, since I found this issue.

It's not uncommon for software to spend a lot of time in 0.x.y.

When I depend on this, I usually write ~> 0.x.y. Eventually once it gets to 1.x.y, I depend on ~> 1.x.

For me, when I'm 0.x.y, I bump y for any bug fixes, and I bump x for new functionality or changes in functionality. This way, my dependencies align up well and I don't get unexpected changes. This gives me some reliability while working on 0.x.y releases across multiple packages.

If I have a library which depends on 0.x.y and I need to depend on a new feature/function, I can bump x.

[jwdonahue]

@AloisMahdal , can you please close this issue? I am trying to reduce the number of open issues to those that have some hope of resulting in a PR. Thank you.

[AloisMahdal]

@AloisMahdal , can you please close this issue? I am trying to reduce the number of open issues to those that have some hope of resulting in a PR. Thank you.

This issue is just informational, for consideration of SemVer users. So, OK.