Version numbers #13
Version numbers #13
Conversation
|
With the work on the series, we started to store the version number as it appears in the title but there's a lack of consistency between the specs leading to different shortname strategy. For instance:
As you can see, the version appearing in the title can affect the choice of the shortname so since |
Co-authored-by: Denis Ah-Kang <[email protected]>
There was a problem hiding this comment.
Not a change introduced by this PR but I had not noticed that the manual of style recommends ["Version" Version_Number]. I'm not aware of any spec that has "Version" in its title. All titles I can think of end with the version number without any prefix. Are there examples?
If not, that does not necessarily mean that the recommendation is wrong but, at a minimum, it would not represent current practice
| @@ -274,6 +274,14 @@ <h3>Document Title</h3> | |||
| convention.</p> | |||
|
|
|||
| <p>Capitalize title words following U.S. usage.</p> | |||
|
|
|||
| <p><code>Part_Number</code>, edition number, and <code>Version_Number</code> | |||
There was a problem hiding this comment.
I would treat Part_Number and edition number separately as I would only expect integers in these cases. That is, "Groovy API Part 2" looks good but "Groovy API Part 2.3" seems wrong. Similarly, "Groovy API 2nd Edition" looks good, but not "Groovy API 2.3 Edition".
| SHOULD take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading | ||
| zeroes. X is the major version, Y is the minor version, and Z is the patch version. X, Y and Z are separated | ||
| by '.' (DOT). Y and Z are optional (2, 2.0, 2.0.0 are equivalent). | ||
| Each element SHOULD increase numerically. Major version one (1.y.z) is for initial development. For additional |
There was a problem hiding this comment.
Usually, Semantic Versioning uses 0 Major for initial development and 1 first public release. Even though we do everything in public the transition from 0 to 1 does indicate a commitment to new stability. Is that not relevant for this use?
https://semver.org/#spec-item-4
https://semver.org/#spec-item-5
There was a problem hiding this comment.
Right but there are no W3C specifications which do this. It would also break pubrules: FPWD to CR would be v0 and then the PR and Rec would be 1.0; then the next version would also be 1.0 until it moved to PR.
I think this would be super confusing.
So best to say that specification versions do not follow Semantic Versioning in this regard.
There was a problem hiding this comment.
OK - Got it
Perhaps spell it out rather than leaving it as a possible type-o?
There was a problem hiding this comment.
What about adopting a suffix notation on the version, so Rec would be 1.0.0, then next update might be 1.1.0[-suffix] or 2.0.0[-suffix]? This is often done on GitHub repos that use semantic versioning.
We could be clever about the suffix we use - instead of "-RC" for Release Candidate, we could put the maturity level, i.e. -WD or -CR etc. The idea is only to remove the suffix when publishing ("releasing") as a Rec.
This addresses #11
cc @dontcallmedom @ashimura