Should a major version increase indicate cutting-edge or rounded-out?

Question

I'm working on a FOSS library whose versions are all 0.x.y . I am wondering when to bump the version up to 1.0.

On the one hand, the switch from 0 to 1 suggests a level of maturity, of the software being rounded out. But on the other hand, a major version increase above 1.x is more likely to indicate a fundamental change or redesign, which is basically the opposite of maturity, stability and well-roundedness.

How would you resolve this dilemma?

Notes:

This is related: When do you change your major/minor/patch version number?
I'm not following "semantic versioning". At least, not necessarily. So far it's been: first number 0, second number of somewhat-but-not-very significant changes, third number for minor changes and tweaks. But every change "breaks the API", because my specific library is basically "just an API" for something else.

Is your library open source? If it was, you'll better give the URL (of its source code or `github` repository) inside your question! — Basile Starynkevitch, Jan 15 '22 at 11:47
Opinion based, yes. Here's how the big boys do it: make sure your version number is at least on par with that of your direct competitor, regardless the state of your software. — Martin Maat, Jan 15 '22 at 13:32
@BasileStarynkevitch: That goes without saying. If it weren't FOSS, then who cares. — einpoklum, Jan 15 '22 at 15:26
Large organizations have version conventions even for proprietary software.... — Basile Starynkevitch, Jan 15 '22 at 16:53
@BasileStarynkevitch: But then I would ask my manager or something. — einpoklum, Jan 15 '22 at 19:13

score 7 · Answer 1 · answered Jan 15 '22 at 12:22

I think your main mistaken idea is this:

a fundamental change or redesign, which is basically the opposite of maturity, stability and well-roundedness

Stability and maturity are only ever going to be relative, and temporary. It is very, very rare for a piece of software to reach a certain point and become "finished" for all time, without any new ideas, new feedback, and new requirements meaning it needs to change. It doesn't sound like you believe your library is in that rare category, so you'll never meet this ideal of a "finally stable" version.

If you leave the first digit as 0 forever, it simply becomes meaningless - version 0.23.5 is actually just version 23.5. It also suggests to users that at some point the library will reach version 1, and maybe they should be wary of using it in production until it does.

If you think your library is ready for production use, and the fundamental design is stable, call it 1.0, and have a plan in mind for that would be a "big enough" change to go to 2.0.

I would also like to challenge your understanding of Semantic Versioning:

But every change "breaks the API", because my specific library is basically "just an API" for something else.

Changing an API can be done without breaking it - if you add a new function, or a new optional parameter, that is not a breaking change; and if you change the recommended easy to do something, but leave the old way in place with extra wrapping code, that is not a breaking change. Regardless of version numbers, if you want people to actually use your library, you should always be thinking about how to avoid breaking changes, because a library that I can only use by rewriting my code every two weeks is a library I will throw away as soon as possible.

"It is very, very rare for a piece of software to reach a certain point and become "finished" for all time" – Everybody knows about TeX, of course, but that's the point: the reason everybody knows about TeX is precisely because it is so unusual in this regard. It's the same reason why even minor airliner incidents make the news while even deadly car crashes don't. — Jörg W Mittag, Jan 15 '22 at 12:39
1. The thing is that the "ready for production use" code is a maturation of the existing design; and there's a new design which opens up new directions, but is likely not ready for production use. 2. I break the API. Methods change, types change, namespaces change, it changes. Naturally, once I make a release, I'm committed to the API in that release and may well make a small "point-release" just to fix a bug without changing the API (although that hasn't happened yet TBH). — einpoklum, Jan 15 '22 at 15:27
@einpoklum it sounds like you need to do two things: 1) Make some decisions, stop changing everything, even if you think of something slightly better, and call that 1.0. Don't let perfect be the enemy of good. 2) Make a "2.0 preview" branch, and try out the new design; then when it's ready, call it 2.0 *and stop changing that* until you have an *important* change to make 3.0. I can't stress enough that if you say to users "the API changes every version", you might as well say "don't use this library". — IMSoP, Jan 15 '22 at 19:47

score 6 · Answer 2 · answered Jan 15 '22 at 13:20

If you were using Semantic Versioning, the answer would be found there:

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

Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

According to Semantic Versioning, you would use version 1.0.0 for the first version of a stable public API. Everything until then (0.x.y versions) would be considered highly unstable. If you were to frequently make breaking or backwards-incompatible changes, you would very quickly increment the major version number. Technically, there's nothing wrong with making frequent breaking changes. However, it would raise questions and concerns during an assessment if you were trying to position your library or API for external consumers.

However, you're not following Semantic Versioning. Because of that, none of the rules of Semantic Versioning apply to you. You could do whatever you want with the versioning and invent the rules as you go along. However, if you do have other people consuming your API, you may end up frustrating them.

I don't think that every change needs to break the API. If that's the problem, that seems to be indicative of other problems. Perhaps there's not enough time being spent to think through API changes and how to make them more appropriate from the beginning, a plan to add functionality without breaking existing clients, or a plan to communicate and roll out deprecations to clients. I'd recommend looking at this as a problem and consider using Semantic Versioning, since it's widely expected for libraries and APIs.

score 4 · Answer 3 · answered Jan 15 '22 at 12:37

There is no "universal rule" for how to version software, nor is there something like a United Nations Global Versioning Police that will arrest you if you get it wrong.

The simple answer is: you do whatever you want. It is certainly helpful for your users if you have a precise, unambiguous, objective specification of your versioning policy, and you stick to that policy, but there is no requirement to have such a policy at all, nor is there a requirement to stick to it, if you have one.

Semantic Versioning is simply one possible such policy that saves you some work in coming up with your own, but it is not the only one. It so happens that a significant portion of developers agree that the SemVer policy is a good fit for their projects, and there are benefits to standardization, but again: you do whatever you want and whatever makes sense for your project and your users.

Should a major version increase indicate cutting-edge or rounded-out?

3 Answers3