43

I have seen many open source projects being labelled as "not production ready" because they have not reached a major version e.g. 1.0.0 using semver.

What is the significance of reaching this milestone? Is there a criteria that must be met for a piece of software to be considered a major version? Or is it arbitrarily decided by the authors of the software?

5
  • Are you asking about 1.0.0 specific version or major version upgrades?
    – Laiv
    Commented Aug 25, 2022 at 9:38
  • Specifically reaching first major version 1.0.0.
    – spinners
    Commented Aug 25, 2022 at 12:49
  • 1
    Sometimes (at least in commercial products) it can be completely driven by marketing. How does 1.1 look to our customers compared to 1.0? I have personally witnessed the released of a version 2.0 as the very first release.
    – Steve
    Commented Aug 25, 2022 at 17:22
  • They have not set the version to 1.0 because they are not production-ready. Not the opposite.
    – Gherman
    Commented Aug 26, 2022 at 22:26
  • @Steve, that's correct. More on version numbers and marketing here: stackoverflow.com/a/71225569/134044
    – NeilG
    Commented Jul 7, 2023 at 0:46

5 Answers 5

66

There is a special difference between 0.0.0 and 1.0.0. Let's dig into the Semantic Versioning standards. The following rules label these numbers as x.y.z:

When x is 0

Chaos rules.

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

Semantic Versioning 2.0.0

When x is greater than 0

Things start meaning things.

  1. 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.

  2. Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.

  3. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.

  4. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented.

Semantic Versioning 2.0.0

So yes there is a magical difference between x going from 0 to 1 vs going from 1 to 2. People are funny about zero.

Of course many projects that still use 0 as their major are stable. The point is you weren't promised that stability by this version number.


Not everything with a version number uses semantic versioning and may not follow these rules. Read the documentation before making assumptions.

Examples:

Web 2.0, Super Bowl XXX, Star Wars Episode V. And just to round out this “gigantic landscape” I give you: Mostly Harmless "The fifth book in the increasingly inaccurately named Hitchhikers Trilogy".

Sorry if I gave the impression that semantic versioning was universal.

6
  • 41
    And of course, you have the famous example of Oracle which started at version 2.3 for marketing reasons, because who is going to trust version 1.x of enterprise software?
    – Chuu
    Commented Aug 24, 2022 at 23:27
  • 2
    Note that this is for software which follow semver, which is a requirement for modules which provide an API in some environments (so users of the module can now when it is safe to upgrade or not), and is also followed by other software, but there is no requirement for a standalone application with no API to follow it.
    – jcaron
    Commented Aug 25, 2022 at 8:45
  • 7
    Not everyone uses SemVer, though. SemVer is a good start, a good idea, but it is also not perfect and has problems, and while advocates of SemVer seem to think it is the holy grail, there are reasons not to use, and many project in fact don't. An answer claiming that only SemVer exists misses a gigantic part of the landscape out there.
    – Polygnome
    Commented Aug 25, 2022 at 9:36
  • 6
    @Polygnome semver was explicitly mentioned in the question, so I think this answer is fine.
    – raznagul
    Commented Aug 25, 2022 at 10:08
  • 1
    @raznagul it does say "e.g. 1.0.0 using semver" - it's not clear whether semver is part of the example or part of the question Commented Aug 26, 2022 at 14:36
22

If the project is using Semantic Versioning, then a 1.0.0 release means that the public API is stable.

Not having a stable public API doesn't necessarily mean that the software isn't of sufficient quality to use in production. The quality depends on the practices that are being used to build the software. There may be projects where a 0.x.y version has good quality, but any update may make breaking changes to the public interfaces and updating by even a patch version could introduce breaking changes, so consumers need to be cautious when applying any updates.

The notion of "breaking changes" and "backwards compatibility" are fairly well defined terms, so it's not entirely arbitrary. However, the creators of the software package will ultimately decide when they are comfortable calling their public API stable and therefore release a 1.0.0 version of the library.

Of course, all of this only applies to projects strictly using Semantic Versioning. If all of the rules and guidelines of SemVer aren't being applied, then it's anyone's guess what the versioning means.

4
  • I don't think If the project is using Semantic Versioning, then a 1.0.0 release means that the public API is stable. is true. Semantic Version 1.0.0. just means that all future 1.x.x versions are backwards-compatible. You're free to go up by however many major version you want in whatever timeframe you want. If you have 11 backwards-incompatible changes and you release all of those one after the other in a single week, you'd be at 12.0.0. by the end of that week. Which could be fine, dependent on your users' needs.
    – tjalling
    Commented Aug 25, 2022 at 10:51
  • 1
    ... but yes. Semantic Version 0 is the exception, where there is e.g. no guarantee that 0.1.2. is in any way compatible with 0.1.1.
    – tjalling
    Commented Aug 25, 2022 at 10:52
  • 3
    @tjalling From the Semantic Versioning site: If you have a stable API on which users have come to depend, you should be 1.0.0. There are also some other cases where 0.x.y is discussed as "unstable" and a leading number that isn't 0 is discussed as "stable". So this is SemVer's phrasing, not mine.
    – Thomas Owens
    Commented Aug 25, 2022 at 13:26
  • ah. I missed that part, my bad.
    – tjalling
    Commented Sep 17, 2022 at 9:41
14

Semantic versioning or not: A major version number > 0 is a declaration by its authors that the software is fit for production use. Or, negatively: A major version of 0 is an explicit statement by the authors that they don't consider it mature enough.

Both statements may be wrong, and my gut feeling is that there are more wrong 1s than 0s, or at least that the 1s are "wronger", because commercial software is written to earn money, and you cannot do that really with version 0. Open source software, by contrast, often matures under a major version 0 to a state that would have warranted more than one major version jump had it been commercial. An overview can be found here.

As an aside, commercial or not: You may feel more comfortable with some version x.42 (including x == 0) than with some version x.0 (no matter the value of x). A major version change often indicates some major refactoring/restructuring/feature adding, which inevitably introduces new bugs. The minor 0 does not indicate that the software is error free but that the errors have not been detected yet, which makes you the truffle pig. A minor version x.42 indicates that a lot of the errors present at x.0 have been eliminated before you started using it.

3
  • A minor version of 0.42 doesn't mean anything different from 42.0 in Semvar; there's been an update of the program, and any previous API has likely been changed. Any maintainer that could release a 0.42 you'd trust would likely also release a 42.0 you could trust.
    – prosfilaes
    Commented Aug 25, 2022 at 14:24
  • @prosfilaes Not sure what you mean. What is Semvar? Semantic versioning? In that case, there is a huge difference. In any case, I almost never know the maintainer. Commented Aug 25, 2022 at 14:29
  • 1
    In at least some commercial software, a bump in major version could simply mean "x amount of time has passed since the last major release", or "You have to buy a new license". There might not be any functional difference between minor and major releases.
    – JonasH
    Commented Aug 26, 2022 at 14:54
6

The significance of a version 1 release is whatever the people releasing version 1 decide it is. It can never be anything else. Yes, there are conventions. Yes, semver is a (greatly over-hyped and poorly-executed) thing. Often a 1.0 release indicates some level of readiness for general use in the author's opinion. But it doesn't have to be that way.

Sometimes a 1.0 release means "we're feature complete, all the significant bugs we know about are fixed, and we're ready for the press releases and champagne."

Sometimes a 1.0 release means "we're not feature complete, and there's a pile of bugs, but marketing says it's time to ship, so here we go!" (this is less of a motivation for most open-source projects, but it depends on the project).

Sometimes a 1.0 release means "we've been at 0.x for 10 years and people are happy, I guess we might as well."

Sometimes a 1.0 release means the first really breaking change since public release (as though the project were following semver without the convention for 0.x).

Sometimes a 1.0 release means "well, we counted up from 0.1 to 0.9, and my calculator says that 0.1 and 0.10 are the same number, so I guess 1.0 is next". The first 28 unreleased internal builds of Apple DOS for the Apple II were versions 0.1 through 2.8. Version 2.8 was renamed 3.0 when it was shipped to private beta users; then some bugs that were found in beta testing got fixes, which resulted in the very first public release being version 3.1.

All in all, it's foolish to think that a 0.x version is more or less ready for production than any other, without knowing something about the project and the conventions it adheres to. An 0.x might be be buggy or a moving target, but that's better assessed by reading changelogs, or by the authors making an explicit statement like "this is alpha software" or "API is subject to change". A version 7 might indicate stability, but it might also indicate that the authors are version-number-happy (and in the case where they are firm adherents of semver, it means that they've broken things at least 6 times already!)

1
  • 1
    This is the correct answer!! I’ve personally written software that have used most of these versioning “strategies” at some point in my career… At the end of the day, it’s just a number
    – Isak Savo
    Commented Sep 1, 2022 at 21:01
-1

In my experience, major and minor versions are up to product management to decide, based on the product/marketing roadmap.

Of course, we can stay more accordingly to semantic versioning for specific components of the product, like internal libraries, external dependencies, etc.

Not the answer you're looking for? Browse other questions tagged or ask your own question.