Clarify language about higher/lower precedence

[dbplunkett]

I don't think this requires an RFC, since I consider it a clarification of semantics rather than changing semantics, but please correct me if anybody thinks otherwise.

The document seems to conflate "higher precedence" and "lower precedence". The term "higher precedence" is roughly equivalent to the terms "precedes" or "ordered before". E.g. in the sentence, "When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version", it should really say "higher precedence".

A source of confusion may be that, on the topic of determining the order of some string composed of elements, the word "precedence" can commonly refer to two closely related but opposite things: 1. The order in which elements should be compared, and 2. The way some given strings should be ordered as a result of that. E.g. when comparing elements, the pre-release identifier has lower precedence than the "normal" version numbers, but when ordering versions, one with a pre-release identifier has higher precedence than the same "normal" version alone. Which of those two concepts is being referred to is usually clear by context, but I think an exception is this sentence: "Pre-release versions have a lower precedence than the associated normal version." That is why, in addition to the higher<->lower change described above, I've also added clarifying language to this sentence.

Note that the clarifying language in that sentence would be obviated and future confusion about higher vs lower precedence avoided if the document used some other term, like "ordered before/after", instead of the term "higher/lower precedence", but that would be a larger change.

[ljharb]

this reads like an incorrect change to me - 1.0.0 is higher than 1.0.0-alpha, as the previous text states, which means a pre-release version indeed has a lower precedence.

[dbplunkett]

1.0.0 is higher in ordering, and therefore has a lower precedence (the quality of preceding) than 1.0.0-alpha. It would be more clear to only use the word "precedence" to refer to the elements of the version string (e.g. "When comparing, the pre-release identifier has a lower precedence than the major/minor/patch numbers."), as opposed to using it to refer to the entire version string. But, as I mentioned, that would be a larger change, and I didn't feel comfortable proposing such a change.

[ljharb]

"higher precedence" means "takes priority over". thus, a prerelease versions always has a lower precedence than the matching non-prerelease version.

[dbplunkett]

@ljharb To me, that doesn't seem to follow. The pre-release version has lower precedence than other components when comparing, but that's not what it's saying. "A pre-release version" (the whole string) has higher precedence than "a normal version" (the whole string), because it comes first (it takes priority, AKA precedes). If that's not what the sentence was trying to refer to, then this part would be logically irrelevant: "When major, minor, and patch are equal".

[ljharb]

It comes first in a list sorted earliest to latest, but that’s not what it’s talking about.

Precedes means it does not take priority.

[dbplunkett]

Sorry, that still doesn't make sense to me. Here are two more wordy examples of rewording lines 124-125, to serve as a demonstration:

"When major, minor, and patch are equal, a version with a pre-release version is ordered before one without."

"When comparing elements to determine ordering, the pre-release version has lower precedence than the normal version numbers."

I made the smallest change I could to try to make the sentence communicate the first concept, but if the sentence is actually trying to communicate the second concept, that would be confusing to me, because:

1. It is inapplicable to the case where either version has no pre-release version.
2. The major, minor, and patch numbers being equal across the two versions is irrelevant.

Maybe the two concepts are being unintentionally combined?

Sorry if what I'm trying to say is still confusing. I think I've done my best to explain it at this point, so I won't persist unless you ask me to.

[ljharb]

The only time “precedence” matters is when sorting, or when choosing between two versions.

Version number lists are most often sorted newest to oldest, so the things with highest “precedence” are at the top of the list - 1.0.0 sorts higher than 1.0.0-x, because the former has higher precedence than the latter.

when choosing between two, the version that is chosen is the one that has a higher precedence. Between 1.0.0 and 1.0.0-x, the former has higher precedence than the latter.

[jwdonahue]

Perhaps we we should start with an English dictionary?

precedence

noun
1 act or fact of preceding.
2 the right to precede in order, rank, or importance; priority.
3 the fact of preceding in time; antedating.
4 the right to precede others in ceremonies or social formalities.
5 the order to be observed in ceremonies by persons of different ranks, as by diplomatic protocol.

So what does "precede" actually mean in this context?

Being lesdyxic, I do find the language in the spec to be mildly confusing, until I compare it to the examples. When it comes to sorting, I first want to know whether I am to output in ascending or descending order, but those terms aren't in the spec and in this case, normal string sorting rules do not apply. The following statements are all true:

• 1 < 2
• In ascending sort order 1 precedes 2.
• In descending order 2 precedes 1.

While the spec implies the later, it is not immediately clear in this regard, until you read all of it, including the examples, and even then, I've always have to think more than usual to grok it. The spec is essentially saying that 1.0.0-r < 1.0.0, even though in terms of string comparisons, 1.0.0-r > 1.0.0 (the former being longer). Every attempt I've made to come up with better wording has failed in the past (damn aixelsid gets me every time).

IMO, the proposed new language is not an improvement over the current spec.

[ljharb]

The relevant definition here is number 5 - "precedence" here is about ranking/ordering, not "preceding".

[dbplunkett]

I am open to the idea that ascending vs descending should be clarified, but I'm not sure. I think it's pretty well understood that, when defining rules for ordering, we are describing the "ascending" rules. E.g. if you have never heard of the alphabet and I am describing alphabetical order to you and I say that 'A' comes before 'B', or 'A' is lower in order than 'B', or 'A' precedes 'B', or 'A' has a higher precedence than 'B', you would typically understand that I am describing the ascending version of the ordering logic.

It is, however, another opportunity to illustrate what I think is the confusing wording in the document, so I'll take one more stab at it:

The document, as Jordan said in 2021, would seem to imply, if it were describing the alphabet, that 'B' has higher precedence than 'A' because it is higher in order. It is true that, unlike letters of the alphabet, version strings get "newer" as they get higher in order, but the document reads to me like it is using the word only to describe order (where a higher precedence would mean appearing earlier in the list). For example, it says, "Precedence refers to how versions are compared to each other when ordered", rather than, "...when choosing the newest version".

I tried to keep my edit minimal, but it would obviate the issue to make a larger change that uses terms like "precedes/follows", "comes before/after", and/or "order"; instead of the term "precedence", which can be ambiguous, especially when used in the phrase "higher/lower precedence". E.g. lines 124-125 might be clearer as, "When major, minor, and patch are equal, a pre-release version precedes a normal version".

Another possibility is changing this definition sentence: "Precedence refers to how versions are compared to each other when ordered." to something like, "Precedence refers to how versions are compared to each other when determining which is newer (a higher precedence indicates a newer version)." But it would still probably be necessary to change the word "precedence" in the few spots it occurs outside of the section headed by that definition sentence.

Jordan, if you think either of those is a sufficient improvement over the existing copy, I will modify my edits to be a little more heavy-handed.

[ljharb]

I personally think "precedence" is perfectly clear, so my only opinions here will be if I think alternative are less clear :-)

I do think that "precedence" implies a subtle connotation that is actually pretty important for ranges - if i specify "*", or 4.x, etc, which should be chosen? While the current spec lacks ranges, #584 would add them, and in that context I think "before/after" isn't actually the best wording.

[jwdonahue]

@dbplunkett Which is the newer or older version is not relevant to this discussion. Lower versions may in fact be released later than higher ones. Chronological order can be affected by policies. The following history is perfectly valid:

1.0.0
2.0.0
3.0.0 // No bugs yet? Let's test it...
3.0.1 // Not as good as we thought we were.
2.0.1 // Our biggest paying customer's are still on 2.x.y.
// We only support current - 1, so no 1.0.1 here.

And this is part of the confusion of using "precedence" in the spec. Many people do rightfully conflate precedence and indeed versioning with chronology. NOT that I am arguing for any changes to the spec. I personally think it's as clear as it can be, given the complexity of the subject matter and its non-conformity to standard string sorting conventions.

[dbplunkett]

@jwdonahue Sorry, you're right - I'm merely using "newer" as an imprecise shorthand for Jordan's context of "which version should be chosen if resolving from a range".

It's true that "precedence" is a useful and specific word in the context of defining which of a set of options should be chosen; or for defining the order in which to compare components between two structures (though I might suggest "priority" as a potential alternative in the latter case). I just don't think that usage is clear as written.

However, I have probably prosecuted my case as best as I can. This PR is pretty old - @ljharb have you left it open only as a courtesy to me? I can close it if you are unmoved.

[jwdonahue]

I personally think that version selectors will always be an implementation detail. Defining a sort order, or any kind of range notation in the spec; limits innovation and nothing the spec can say will prevent someone from implementing whatever policies they have need of. I wrote a tool that currently has more than 10K users that can also sort on the meta tag, which is very useful for automated testing and policy enforcement.

[ljharb]

@dbplunkett i'm not a maintainer here :-) just offering my thoughts.

Version selectors are going to end up in the semver spec, likely #584 or something strikingly similar.