From 37257b45e9030fa28cea1ac7c0a55bf78049a1f8 Mon Sep 17 00:00:00 2001
From: Josh Triplett <josh@joshtriplett.org>
Date: Wed, 17 Jul 2024 13:21:45 -0700
Subject: [PATCH] style-guide: Clarify version-sorting

Every time we apply version-sorting, we also say to sort non-lowercase before
lowercase. This seems likely to be what we'll want for future sorting,
as well. For simplicity, just incorporate that into the definition,
"unless otherwise specified".
---
 src/doc/style-guide/src/README.md | 34 ++++++++++++++++++-------------
 src/doc/style-guide/src/items.md  | 10 +++------
 2 files changed, 23 insertions(+), 21 deletions(-)

diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md
index dce50ebf29c46..f42b9cb597843 100644
--- a/src/doc/style-guide/src/README.md
+++ b/src/doc/style-guide/src/README.md
@@ -117,8 +117,7 @@ fn baz() {}
 In various cases, the default Rust style specifies to sort things. If not
 otherwise specified, such sorting should be "version sorting", which ensures
 that (for instance) `x8` comes before `x16` even though the character `1` comes
-before the character `8`. (If not otherwise specified, version-sorting is
-lexicographical.)
+before the character `8`.
 
 For the purposes of the Rust style, to compare two strings for version-sorting:
 
@@ -132,12 +131,13 @@ For the purposes of the Rust style, to compare two strings for version-sorting:
   these strings, treat the chunks as equal (moving on to the next chunk) but
   remember which string had more leading zeroes.
 - To compare two chunks if both are not numeric, compare them by Unicode
-  character lexicographically, except that `_` (underscore) sorts immediately
-  after ` ` (space) but before any other character. (This treats underscore as
-  a word separator, as commonly used in identifiers.)
-  - If the use of version sorting specifies further modifiers, such as sorting
-    non-lowercase before lowercase, apply those modifiers to the lexicographic
-    sort in this step.
+  character lexicographically, with two exceptions:
+  - `_` (underscore) sorts immediately after ` ` (space) but before any other
+    character. (This treats underscore as a word separator, as commonly used in
+    identifiers.)
+  - Unless otherwise specified, version-sorting should sort non-lowercase
+    characters (characters that can start an `UpperCamelCase` identifier)
+    before lowercase characters.
 - If the comparison reaches the end of the string and considers each pair of
   chunks equal:
   - If one of the numeric comparisons noted the earliest point at which one
@@ -157,7 +157,17 @@ leading zeroes.
 
 As an example, version-sorting will sort the following strings in the order
 given:
-- `_ZYWX`
+- `_ZYXW`
+- `_abcd`
+- `A2`
+- `ABCD`
+- `Z_YXW`
+- `ZY_XW`
+- `ZY_XW`
+- `ZYXW`
+- `ZYXW_`
+- `a1`
+- `abcd`
 - `u_zzz`
 - `u8`
 - `u16`
@@ -190,11 +200,7 @@ given:
 - `x86_64`
 - `x86_128`
 - `x87`
-- `Z_YWX`
-- `ZY_WX`
-- `ZYW_X`
-- `ZYWX`
-- `ZYWX_`
+- `zyxw`
 
 ### [Module-level items](items.md)
 
diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md
index c0628691b7734..8e1b1d80fb644 100644
--- a/src/doc/style-guide/src/items.md
+++ b/src/doc/style-guide/src/items.md
@@ -489,10 +489,8 @@ foo::{
 A *group* of imports is a set of imports on the same or sequential lines. One or
 more blank lines or other items (e.g., a function) separate groups of imports.
 
-Within a group of imports, imports must be version-sorted, except that
-non-lowercase characters (characters that can start an `UpperCamelCase`
-identifier) must be sorted before lowercase characters. Groups of imports must
-not be merged or re-ordered.
+Within a group of imports, imports must be version-sorted. Groups of imports
+must not be merged or re-ordered.
 
 E.g., input:
 
@@ -520,9 +518,7 @@ re-ordering.
 ### Ordering list import
 
 Names in a list import must be version-sorted, except that:
-- `self` and `super` always come first if present,
-- non-lowercase characters (characters that can start an `UpperCamelCase`
-  identifier) must be sorted before lowercase characters, and
+- `self` and `super` always come first if present, and
 - groups and glob imports always come last if present.
 
 This applies recursively. For example, `a::*` comes before `b::a` but `a::b`