0

Why do some GitHub repos have 0.x.y releases if version 1.0.0 is the first public API release per SemVer2? Isn't 0.x.y development before the first complete working code you want to release to the public (i.e. wouldn't anything pre-1.0 not be usable)? I am specifically referring to repos that want to claim they are following semantic versioning.

THOUGHT: Is a release in the 0.x.y phase usable code that just doesn't have API documentation yet? Is that what that means?

e.g. Tensorflow has releases on GitHub starting at 0.5.0. Is this acceptable per semantic versioning, or are they simply not following semver and using something else?

adam.hendry
  • 4,458
  • 5
  • 24
  • 51
  • A project's versioning can easily differ. I've seen people refer to their code starting as 1.0.0 and at 0.0.1. Generally 1.0.0 refers to stable, but `pandas` was < 1.0.0 until recently. – astrochun Feb 17 '21 at 03:44
  • @astrochun What makes a version unstable? Conversely, how are we "sure" a version is stable? – adam.hendry Feb 17 '21 at 03:52
  • @astrochun I should also add, your answer is fair: those repos might not be following semantic versioning. I will edit my question to reflect specifically I'm considering repos that claim to follow semver. – adam.hendry Feb 17 '21 at 04:01
  • Unstable can be a number of things. It could have old dependencies, fails common unit tests, etc. Keep in mind there's a difference between public vs an official release announcement. The authors may be developing it but haven't fully announce it. – astrochun Feb 17 '21 at 04:08
  • Keep in mind that triggering on a GitHub release is one way for deployment so it could be helpful on the CI/CD side. – astrochun Feb 17 '21 at 04:26
  • @astrochun That is very interesting. Great info! I want to learn more because I'm having a hard time finding resources covering this online. Is there a way official releases are indicated on GitHub as opposed to public releases? And what's up with pre-releases? How do I know what to expect with any given public version I can download? – adam.hendry Feb 17 '21 at 04:35

1 Answers1

2

From the spec:

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.

Why do some GitHub repos have 0.x.y releases if version 1.0.0 is the first public API release per SemVer2?

Because the maintainers do not wish to give the impression that their code/API's are stable or ready for production. They are reserving the right to remove or modify any of their API's without warning, for any reason they deem appropriate.

THOUGHT: Is a release in the 0.x.y phase usable code that just doesn't have API documentation yet? Is that what that means?

It means exactly what the spec says it means. If that's not clear enough, then you'd have to ask each of those repo's maintainers, what they think it means. In general, you should always treat prerelease versions as dangerous, unreliable, and subject to change without notice. Do not deploy any prerelease version into production, without thorough testing prior to deployment.

e.g. Tensorflow has releases on GitHub starting at 0.5.0. Is this acceptable per semantic versioning, or are they simply not following semver and using something else?

You should ask them if they are following SemVer. Any random version triple may have the appearance of a SemVer string, but that does not mean the publisher is adhering to SemVer. If they say they are SemVer and the first publicly available version is 0.5.0, that's perfectly acceptable. It is common practice to start at 0.1.0 for prerelease of the first feature(s), but there is no rule that requires it. There is also no requirement that older, possibly less stable versions, be left in public view. Nor is there a requirement for continuity of the version history. Any random version may be removed from public view for any reason the publisher deems sufficient cause to remove them.


When a publisher issues their first major version, they are saying "here's an API that we will not break". The SemVer spec allows them to fix bugs in their code and documentation with patch level version bumps, and add non-breaking features with minor level version bumps. The spec does not say how big those bumps should be.

jwdonahue
  • 6,199
  • 2
  • 21
  • 43