Move rules to the contributor guide

ehuss · ehuss · commit 63cbb464d5b4 · 2025-11-25T11:47:25.000-08:00
diff --git a/contributor-guide/src/SUMMARY.md b/contributor-guide/src/SUMMARY.md
@@ -10,8 +10,8 @@
 - [Formatting](formatting/index.md)
     - [Markdown](formatting/markdown.md)
     - [Admonitions](formatting/admonitions.md)
-- [Language rules]()
-    - [rustc test annotations]()
+- [Language rules](rules/index.md)
+    - [rustc test annotations](rules/test-annotations.md)
 - [Examples](examples.md)
 - [Links](links.md)
 - [Rust grammar](grammar.md)
diff --git a/contributor-guide/src/rules/index.md b/contributor-guide/src/rules/index.md
@@ -0,0 +1,44 @@
+# Language rules
+
+Clauses within the Reference are labeled with a named *rule*. This provides the ability to link and refer to individual clauses, and to [link to the `rustc` testsuite](test-annotations.md).
+
+## Rule labels
+
+Most clauses should be preceded with a rule label. A rule label should be on a line by itself, and should look like this:
+
+```markdown
+r[foo.bar]
+```
+
+The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`).
+
+Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are [automatic link references] so that any rule can be referred to from any page in the book.
+
+In the HTML, the rules are clickable just like headers.
+
+## Rule guidelines
+
+When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines:
+
+1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to.
+2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break.
+    - This content will be moved to `[!NOTE]` or more specific admonitions in the future.
+3. Rust code examples and tests do not need their own rules.
+4. Use the following guidelines for admonitions:
+    - Notes: Do not include a rule.
+    - Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules.
+    - Target specific behavior: Always include the rule.
+    - Edition differences: Always include the rule.
+5. The following keywords should be used to identify paragraphs when unambiguous:
+    - `intro`: The beginning paragraph of each section - should explain the construct being defined overall.
+    - `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used.
+    - `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`).
+6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows:
+    - If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s).
+    - Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule".
+    - Whenever possible, do not repeat previous components of the rule.
+    - Edition differences admonitions should typically be named by the edition where the behavior changed. You should be able to correspond the dates to the chapters in <https://doc.rust-lang.org/edition-guide/>.
+    - Target specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS).
+    - Use an appropriately descriptive, but short, name if the language does not provide one.
+
+[automatic link references]: ../links.md#rule-links
diff --git a/contributor-guide/src/rules/test-annotations.md b/contributor-guide/src/rules/test-annotations.md
@@ -0,0 +1,15 @@
+# rustc test annotations
+
+Tests in <https://github.com/rust-lang/rust> can be linked to rules in the reference. The rule will include a link to the tests, and there is also an [appendix] which tracks how the rules are currently linked.
+
+Tests in the `tests` directory can be annotated with the `//@ reference: x.y.z` header to link it to a rule. The header can be specified multiple times if a single file covers multiple rules.
+
+Compiler developers are not expected to add `reference` annotations to tests. However, if they do want to help, their cooperation is very welcome. Reference authors and editors are responsible for making sure every rule has a test associated with it.
+
+The tests are beneficial for reviewers to see the behavior of a rule. It is also a benefit to readers who may want to see examples of particular behaviors. When adding new rules, you should wait until the reference side is approved before submitting a PR to `rust-lang/rust` (to avoid churn if we decide on different names).
+
+Prefixed rule names should not be used in tests. That is, do not use something like `asm.rules` when there are specific rules like `asm.rules.reg-not-input`.
+
+We are not expecting 100% coverage at any time. Although it would be nice, it is unrealistic due to the sequence things are developed, and resources available.
+
+[appendix]: https://doc.rust-lang.org/nightly/reference/test-summary.html
diff --git a/docs/authoring.md b/docs/authoring.md
@@ -12,63 +12,6 @@ To verify that links are not broken, run `cargo xtask linkcheck`.
 
 As a last step before opening a PR, it is recommended to run `cargo xtask test-all`. This will go through and run most of the tests that are required for CI to pass. See `xtask/src/main.rs` for what all this does.
 
-## Special markdown constructs
-
-The following are extensions provided by [`mdbook-spec`](https://github.com/rust-lang/spec/tree/main/mdbook-spec).
-
-### Rules
-
-Most clauses should be preceded with a rule. Rules can be specified in the markdown source with the following on a line by itself:
-
-```markdown
-r[foo.bar]
-```
-
-The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`).
-
-Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are automatic link references so that any rule can be referred to from any page in the book.
-
-In the HTML, the rules are clickable just like headers.
-
-When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines:
-
-1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to.
-2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break.
-    * This content will be moved to `[!NOTE]` or more specific admonitions in the future.
-3. Rust code examples and tests do not need their own rules.
-4. Use the following guidelines for admonitions:
-    * Notes: Do not include a rule.
-    * Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules.
-    * Target specific behavior: Always include the rule.
-    * Edition differences: Always include the rule.
-5. The following keywords should be used to identify paragraphs when unambiguous:
-    * `intro`: The beginning paragraph of each section - should explain the construct being defined overall.
-    * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used.
-    * `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`).
-6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows:
-    * If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s).
-    * Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule".
-    * Whenever possible, do not repeat previous components of the rule.
-    * Edition differences admonitions should typically be named by the edition where the behavior changed. You should be able to correspond the dates to the chapters in <https://doc.rust-lang.org/edition-guide/>.
-    * Target specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS).
-    * Use an appropriately descriptive, but short, name if the language does not provide one.
-
-#### Test rule annotations
-
-Tests in <https://github.com/rust-lang/rust> can be linked to rules in the reference. The rule will include a link to the tests, and there is also an [appendix] which tracks how the rules are currently linked.
-
-Tests in the `tests` directory can be annotated with the `//@ reference: x.y.z` header to link it to a rule. The header can be specified multiple times if a single file covers multiple rules.
-
-Compiler developers are not expected to add `reference` annotations to tests. However, if they do want to help, their cooperation is very welcome. Reference authors and editors are responsible for making sure every rule has a test associated with it.
-
-The tests are beneficial for reviewers to see the behavior of a rule. It is also a benefit to readers who may want to see examples of particular behaviors. When adding new rules, you should wait until the reference side is approved before submitting a PR to `rust-lang/rust` (to avoid churn if we decide on different names).
-
-Prefixed rule names should not be used in tests. That is, do not use something like `asm.rules` when there are specific rules like `asm.rules.reg-not-input`.
-
-We are not expecting 100% coverage at any time. Although it would be nice, it is unrealistic due to the sequence things are developed, and resources available.
-
-[appendix]: https://doc.rust-lang.org/nightly/reference/test-summary.html
-
 ## Style
 
 Idioms and styling:
