Chapter 2. Improvement about SemVer

File: src/ch02-00-guessing-game-tutorial.md
Book: p. 20 § 2

Cargo considers these versions to have public APIs compatible with version 0.8.5, and this specification ensures you’ll get the latest patch release that will still compile with the code in this chapter. Any version 0.9.0 or greater is not guaranteed to have the same API as what the following examples use.

Problem

It's a very helpful introduction to semantic versioning, but there's a misconception that should be nipped in the bud. As the SemVer document referenced in the Cargo Book states in 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.

The important point is: crates with major version 0 are not to be considered stable APIs; they're in initial development (alpha, beta), even if Cargo has this rule about the first non-null digit.

A significant problem with many crates is that they're actively used while still technically unstable, even after years. I assume that a fair share of them are actually stable but still with a major version 0 by mistake. It would be a good opportunity to educate further generations about this so that, hopefully, the version numbers become less confusing in the future. It would also be more accurate to mention it.

Suggestion

I would suggest this modification:

Cargo considers these versions to have public APIs compatible with version 0.8.5, and this specification ensures you’ll get the latest patch release that will still compile with the code in this chapter. It will consider versions 0.9.0 or greater as not guaranteed to have the same API_ as what the following examples use_. [N: I'm not sure what that last part that I put in italics means, perhaps remove it?)

I would then add:

Note that Semantic Versioning clearly states that major version zero (0.y.z) is for initial development and that anything may change at any time. The public API in those versions shouldn't be considered stable. This also means that, once your code and API are considered stable, you should increase to the major version 1 so that its users are aware of its new status.

Open src/ch02-00-guessing-game-tutorial.md at Chapter 2, page 20, section 2, and compare the current SemVer wording with the linked SemVer specification. Revise the explanation so it distinguishes Cargo's compatibility rule from the instability of 0.y.z versions, then verify that the chapter accurately communicates when a stable API should use version 1.0.