search

semver / semver.org

Semantic Versioning spec and website
https://semver.org
496 stars 282 forks source link

Splitting the specification points into sub-sections #264

Open judgej opened 6 years ago

judgej commented 6 years ago

Each numbered requirement in the specification has a dozen requirements within it, in a rambling paragraph. Could each of those points be put into their own sub-section paragraph or bullet point?

Something like this (though github markdown is choosing the numbering format here):

  1. Pre-release versions. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
    1. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version.
    2. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-].
    3. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes.
    4. Pre-release versions have a lower precedence than the associated normal version.
    5. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.
jwdonahue commented 6 years ago

Some say tomoto some say tamata. It would be nice to be able to reference individual clauses in a URL, but it would add substantial length to the document as well. I suppose it would be easier to read on a small screen. I kind of like it as-is, but then, I learned to read long before twitter came along, so I see every clause without them having to be listed vertically and I rarely use my phone to browse the web.

I've recently been exposed to some XML document formats that could be displayed in either mode by selecting the CSS to use on the page. That would be very cool. @judgej, are you volunteering?

jwdonahue commented 6 years ago

@Haacked, this might be worthy of future consideration. I would move it over to semver/semver.org and tag it as nice-to-have, but I don't have the magic for that.