[GH-ISSUE #561] Improve item 11 #4652

New Issue

GiteaMirror · 2026-06-13T12:56:55-05:00

GiteaMirror commented

2026-06-13 12:56:55 -05:00

Originally created by @tomschr on GitHub (Apr 18, 2020).
Original GitHub issue: https://github.com/semver/semver/issues/561

Situation

While working on a semver related library, I've had to read item 11 of the specification for clarification. It states (emphasized by me):

Precedence refers to how versions are compared to each other when ordered.
[...]
When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version.
Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: [...]

The ellipsis contains the following rules (cited from the spec, but reformatted for better readability):

Identifiers consisting of only digits are compared numerically.
Identifiers with letters or hyphens are compared lexically in ASCII sort order.
Numeric identifiers always have lower precedence than non-numeric identifiers.
A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.

Question

I'm trying to understand how the above rules are applied to a specific prerelease. How does the spec compare when one of the prereleases has a dot and the other don't? For example:

 1.0.0-beta1 < 1.0.0-beta.2

(Keep in mind the dot in beta.2 and the absence in beta1).

From my understanding, the spec has a gap here. It doesn't specify if such a dot is taken into account or not (or it is and I misread it).

IMHO, most people would assume that the above expression would evaluate to true. My emphasized phrase phrase seems not to take into account if a dot itself matters. Is my observation correct or is my understanding wrong?

Proposal

IMHO, the specification is not clear enough on this particular example. I would propose to extend item 11 with:

a clarifying sentence if such a dot is skipped or not, and
an additional version inserted in the example.

Currently, the example in the spec looks like this:

Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

I would propose to extend it to clarify the order of a prerelease without a dot:

Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta3 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

If you don't agree, then please try to reformat item 11. It's a long block of text and it would help to understand if you introduce a list as I've shown in the beginning. 😉

Thanks! Hope it does make sense. 😉

Originally created by @tomschr on GitHub (Apr 18, 2020). Original GitHub issue: https://github.com/semver/semver/issues/561 # Situation While working on a semver related library, I've had to read [item 11](https://semver.org/#spec-item-11) of the specification for clarification. It states (emphasized by me): > Precedence refers to how versions are compared to each other when ordered. > [...] > When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version. > Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by **comparing each dot separated identifier from left to right until a difference is found as follows**: [...] The ellipsis contains the following rules (cited from the spec, but reformatted for better readability): * Identifiers consisting of only digits are compared numerically. * Identifiers with letters or hyphens are compared lexically in ASCII sort order. * Numeric identifiers always have lower precedence than non-numeric identifiers. * A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. # Question I'm trying to understand how the above rules are applied to a specific prerelease. How does the spec compare when one of the prereleases has a dot and the other don't? For example: 1.0.0-beta1 < 1.0.0-beta.2 (Keep in mind the dot in `beta.2` and the absence in `beta1`). From my understanding, the spec has a gap here. It doesn't specify if such a dot is taken into account or not (or it is and I misread it). IMHO, most people would assume that the above expression would evaluate to true. My emphasized phrase phrase seems not to take into account if a dot **itself** matters. Is my observation correct or is my understanding wrong? # Proposal IMHO, the specification is not clear enough on this particular example. I would propose to extend item 11 with: * a clarifying sentence if such a dot is skipped or not, and * an additional version inserted in the example. Currently, the example in the spec looks like this: Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0. I would propose to extend it to clarify the order of a prerelease **without** a dot: Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < **1.0.0-beta3** < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0. If you don't agree, then please try to reformat item 11. It's a long block of text and it would help to understand if you introduce a list as I've shown in the beginning. :wink: Thanks! Hope it does make sense. :wink:

GiteaMirror added the question label 2026-06-13 12:56:55 -05:00

GiteaMirror closed this issue

2026-06-13 12:56:56 -05:00

GiteaMirror commented

2026-06-13 12:56:57 -05:00

@klehelley commented on GitHub (Apr 20, 2020):

What about identifiers that end with numbers that should not be evaluated as if a dot was there?

In your example, things are IMO pretty clear:

1.0.0-beta1:
- Major: 1
- Minor: 0
- Patch: 0
- Pre-release version with identifiers:
  - beta1 (alphanumeric)
1.0.0-beta.2:
- Major: 1
- Minor: 0
- Patch: 0
- Pre-release version with identifiers:
  - beta (alphanumeric)
  - 2 (numeric)

Looking at the first difference between these two version strings, we have the first pre-release identifiers: beta < beta1. The comparison can stop here, and as a consequence the precedence rules state that 1.0.0-beta.2 < 1.0.0-beta1.

If this result is not what is expected, the fault here is on the project maintainer being inconsistent in naming versions. The spec seems pretty clear to me in the way a SemVer string is structured and how to compare two of them. I do agree however that rule 11 is a bit of a mouthful, presented in a single paragraph on the current spec.

@klehelley commented on GitHub (Apr 20, 2020): What about identifiers that end with numbers that _should not_ be evaluated as if a dot was there? In your example, things are IMO pretty clear: - `1.0.0-beta1`: - Major: 1 - Minor: 0 - Patch: 0 - Pre-release version with identifiers: - beta1 (alphanumeric) - `1.0.0-beta.2`: - Major: 1 - Minor: 0 - Patch: 0 - Pre-release version with identifiers: - beta (alphanumeric) - 2 (numeric) Looking at the first difference between these two version strings, we have the first pre-release identifiers: `beta` < `beta1`. The comparison can stop here, and as a consequence the precedence rules state that `1.0.0-beta.2` < `1.0.0-beta1`. If this result is not what is expected, the fault here is on the project maintainer being inconsistent in naming versions. The spec seems pretty clear to me in the way a SemVer string is structured and how to compare two of them. I do agree however that rule 11 is a bit of a mouthful, presented in a single paragraph on the current spec.

GiteaMirror commented

2026-06-13 12:56:57 -05:00

@tomschr commented on GitHub (Apr 20, 2020):

@klehelley Thanks Kévin for your detailed answer! Much appreciated. 👍

After your explanation and rereading the paragraph, I understand now how this is meant. I can accept it. 👍

However, I still think, the wording can be improved. Maybe it's my limited understanding of the English language, but not all are native speakers. 😉 We all have different (language) backgrounds. Especially for a specification, clarity is of uttermost importance. That's why I'm so picky. 😆

Sure, there are translations. Depending on who translated it, it can introduce a different meaning. In my case, I try to read the original spec as much as I can although there is a translation available for my language.

Improving item 11 would not only help the original English spec, but all translations would benefit from this.

I do agree however that rule 11 is a bit of a mouthful, presented in a single paragraph on the current spec.

May I suggest to use my suggestion from above? You don't have to change the wording, it would only introduce a list and the items would be the conditions. I'm sure this would make the whole item 11 a lot more accessible.

Would that be an approach to pursue?

@tomschr commented on GitHub (Apr 20, 2020): @klehelley Thanks Kévin for your detailed answer! Much appreciated. :+1: After your explanation and rereading the paragraph, I understand now how this is meant. I can accept it. :+1: However, I still think, the wording can be improved. Maybe it's my limited understanding of the English language, but not all are native speakers. :wink: We all have different (language) backgrounds. Especially for a specification, clarity is of uttermost importance. That's why I'm so picky. :laughing: Sure, there are translations. Depending on who translated it, it can introduce a different meaning. In my case, I try to read the original spec as much as I can although there is a translation available for my language. Improving item 11 would not only help the original English spec, but all translations would benefit from this. > I do agree however that rule 11 is a bit of a mouthful, presented in a single paragraph on the current spec. May I suggest to use my suggestion from above? You don't have to change the wording, it would only introduce a list and the items would be the conditions. I'm sure this would make the whole item 11 a lot more accessible. Would that be an approach to pursue?

GiteaMirror commented

2026-06-13 12:56:58 -05:00

@jwdonahue commented on GitHub (Jun 9, 2020):

I think a state machine diagram would be most appropriate. Any shuffling of the text is always going to create new difficulties for somebody, while possibly clearing things up for someone else. I think one goal of the spec is to keep the verbiage as terse as possible, while still providing enough clarity that someone who studies the spec and thinks about its implications, is usually going to get it right.

Adding a diagram for the sorting algorithm that is implicitly specified by the spec, would beat any combination of examples you could list in the text.

@jwdonahue commented on GitHub (Jun 9, 2020): I think a state machine diagram would be most appropriate. Any shuffling of the text is always going to create new difficulties for somebody, while possibly clearing things up for someone else. I think one goal of the spec is to keep the verbiage as terse as possible, while still providing enough clarity that someone who studies the spec and thinks about its implications, is usually going to get it right. Adding a diagram for the sorting algorithm that is implicitly specified by the spec, would beat any combination of examples you could list in the text.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#4652