Merge branch 'main' into feat/pointer-comparison-rule

Author: plaindocs

.github/ISSUE_TEMPLATE/CODING-GUIDELINE.yml

@@ -2,8 +2,7 @@ name: Coding Guideline
 description: File a coding guideline of interest
 title: "[Coding Guideline]: "
 labels: ["coding guideline"]
-assignees:
-  - PLeVasseur
+assignees: []
 body:
   - type: markdown
     attributes:
@@ -122,8 +121,14 @@ body:
     id: amplification
     attributes:
       label: Amplification
-      description: An Amplification is a chance to expand or clarify the Guideline's Title. Optional as needed. Normative. Rationale should not be entered here, but below in Rationale.
-      placeholder: In particular, it's important to not `foo` when `bar` under typical conditions of `baz`
+      description: |
+        An Amplification is a chance to expand or clarify the Guideline's Title. Optional as needed. Normative. Rationale should not be entered here, but below in Rationale.
+        
+        **Citing references:** To cite a bibliography entry, use `[CITATION-KEY]` syntax (e.g., `[RUST-REF-UNION]`). These will be automatically linked to your bibliography entries.
+      placeholder: |
+        In particular, it's important to not `foo` when `bar` under typical conditions of `baz`.
+        
+        As documented in [RUST-REF-UNION], this behavior is undefined.
     validations:
       required: false
   - type: textarea
@@ -138,39 +143,291 @@ body:
     id: rationale
     attributes:
       label: Rationale
-      description: Here we explain the why of this Coding Guideline. Should be as long or as short as needed. Non-normative.
-      placeholder: As documented in the below reference, we see that under conditions `baz` if we `foo` when `bar`-ing we encounter suprising behavior `biz`. ...
+      description: |
+        Here we explain the why of this Coding Guideline. Should be as long or as short as needed. Non-normative.
+        
+        **Citing references:** To cite a bibliography entry, use `[CITATION-KEY]` syntax (e.g., `[RUST-REF-UNION]`). These will be automatically linked to your bibliography entries.
+      placeholder: |
+        As documented in the below reference, we see that under conditions `baz` if we `foo` when `bar`-ing we encounter surprising behavior `biz`.
+        
+        The Rust Reference [RUST-REF-UNION] explains this in detail.
     validations:
       required: true
+
+  # ==========================================================================
+  # Non-Compliant Example 1 (Required)
+  # ==========================================================================
+  - type: markdown
+    attributes:
+      value: |
+        ---
+        ## Non-Compliant Examples
+
+        Provide at least one non-compliant example. You may add up to 4 total.
   - type: textarea
-    id: non-compliant-example-prose
+    id: non-compliant-example-prose-1
     attributes:
-      label: Non-Compliant Example - Prose
+      label: Non-Compliant Example 1 - Prose
       description: Here we write a textual description of why the Non-Compliant Example - Code exhibits unintended or consequential behavior. Non-normative.
       placeholder: As seen below in the `non_compliant_example()` function, when `baz` and `bar` are both active and we `foo`, later during refactoring it's possible to get `biz` instead of `boz` behavior. ...
     validations:
       required: true
   - type: textarea
-    id: non-compliant-example-code
+    id: non-compliant-example-code-1
     attributes:
-      label: Non-Compliant Example - Code
-      description: Here we write a code example showcasing the unintended or consequential behavior. Non-normative.
-      placeholder: fn non_compliant_example() { /* ... */ }
+      label: Non-Compliant Example 1 - Code
+      description: |
+        Code example showcasing the unintended or consequential behavior. Non-normative. Please wrap your code in a fenced code block with the `rust` language specifier.
+
+        **Hidden lines:** If your code needs `use` statements, a `fn main()` wrapper, or other boilerplate to compile, but you don't want them shown in the documentation, prefix those lines with `# ` (hash + space). These lines will be compiled but hidden in the rendered docs.
+
+        Example with hidden lines:
+        ````
+        ```rust
+        # use std::mem::MaybeUninit;
+        # fn main() {
+        let x: u32 = unsafe { MaybeUninit::uninit().assume_init() }; // UB
+        # }
+        ```
+        ````
+      placeholder: |
+        ```rust
+        # use std::collections::HashMap;
+        # fn main() {
+        let map = HashMap::new();
+        # }
+        ```
     validations:
       required: true
+
+  # ==========================================================================
+  # Non-Compliant Example 2 (Optional)
+  # ==========================================================================
+  - type: textarea
+    id: non-compliant-example-prose-2
+    attributes:
+      label: Non-Compliant Example 2 - Prose (Optional)
+      description: Additional non-compliant example prose. Leave empty if not needed.
+      placeholder: Another scenario where this guideline is violated...
+    validations:
+      required: false
+  - type: textarea
+    id: non-compliant-example-code-2
+    attributes:
+      label: Non-Compliant Example 2 - Code (Optional)
+      description: Additional non-compliant code example. Leave empty if not needed.
+      placeholder: |
+        ```rust
+        # fn main() {
+        // Another non-compliant example
+        # }
+        ```
+    validations:
+      required: false
+
+  # ==========================================================================
+  # Non-Compliant Example 3 (Optional)
+  # ==========================================================================
+  - type: textarea
+    id: non-compliant-example-prose-3
+    attributes:
+      label: Non-Compliant Example 3 - Prose (Optional)
+      description: Additional non-compliant example prose. Leave empty if not needed.
+      placeholder: Yet another scenario where this guideline is violated...
+    validations:
+      required: false
   - type: textarea
-    id: compliant-example-prose
+    id: non-compliant-example-code-3
     attributes:
-      label: Compliant Example - Prose
+      label: Non-Compliant Example 3 - Code (Optional)
+      description: Additional non-compliant code example. Leave empty if not needed.
+      placeholder: |
+        ```rust
+        # fn main() {
+        // Another non-compliant example
+        # }
+        ```
+    validations:
+      required: false
+
+  # ==========================================================================
+  # Non-Compliant Example 4 (Optional)
+  # ==========================================================================
+  - type: textarea
+    id: non-compliant-example-prose-4
+    attributes:
+      label: Non-Compliant Example 4 - Prose (Optional)
+      description: Additional non-compliant example prose. Leave empty if not needed.
+      placeholder: A fourth scenario where this guideline is violated...
+    validations:
+      required: false
+  - type: textarea
+    id: non-compliant-example-code-4
+    attributes:
+      label: Non-Compliant Example 4 - Code (Optional)
+      description: Additional non-compliant code example. Leave empty if not needed.
+      placeholder: |
+        ```rust
+        # fn main() {
+        // Another non-compliant example
+        # }
+        ```
+    validations:
+      required: false
+
+  # ==========================================================================
+  # Compliant Example 1 (Required)
+  # ==========================================================================
+  - type: markdown
+    attributes:
+      value: |
+        ---
+        ## Compliant Examples
+
+        Provide at least one compliant example. You may add up to 4 total.
+  - type: textarea
+    id: compliant-example-prose-1
+    attributes:
+      label: Compliant Example 1 - Prose
       description: Here we write a textual description of why the Compliant Example - Code avoids unintended or consequential behavior by following the Coding Guideline.
       placeholder: As seen below in the `compliant_example()` function, when `baz` and `bar` are both active and we avoid doing `foo`, later during refactoring we've prevented an error by construction. ...
     validations:
       required: true
   - type: textarea
-    id: compliant-example-code
+    id: compliant-example-code-1
     attributes:
-      label: Compliant Example - Code
-      description: Here we write a code example showcasing we avoid unintended or consequential behavior by following the Coding Guideline.
-      placeholder: fn compliant_example() { /* ... */ }
+      label: Compliant Example 1 - Code
+      description: |
+        Code example showcasing we avoid unintended or consequential behavior by following the Coding Guideline. Please wrap your code in a fenced code block with the `rust` language specifier.
+
+        **Hidden lines:** If your code needs `use` statements, a `fn main()` wrapper, or other boilerplate to compile, but you don't want them shown in the documentation, prefix those lines with `# ` (hash + space). These lines will be compiled but hidden in the rendered docs.
+
+        Example with hidden lines:
+        ````
+        ```rust
+        # use std::collections::HashMap;
+        # fn main() {
+        let mut map = HashMap::new();
+        map.insert("key", "value"); // Compliant usage
+        # }
+        ```
+        ````
+      placeholder: |
+        ```rust
+        # fn main() {
+        let safe_value = 42u32; // Properly initialized
+        # }
+        ```
     validations:
       required: true
+
+  # ==========================================================================
+  # Compliant Example 2 (Optional)
+  # ==========================================================================
+  - type: textarea
+    id: compliant-example-prose-2
+    attributes:
+      label: Compliant Example 2 - Prose (Optional)
+      description: Additional compliant example prose. Leave empty if not needed.
+      placeholder: Another way to comply with this guideline...
+    validations:
+      required: false
+  - type: textarea
+    id: compliant-example-code-2
+    attributes:
+      label: Compliant Example 2 - Code (Optional)
+      description: Additional compliant code example. Leave empty if not needed.
+      placeholder: |
+        ```rust
+        # fn main() {
+        // Another compliant example
+        # }
+        ```
+    validations:
+      required: false
+
+  # ==========================================================================
+  # Compliant Example 3 (Optional)
+  # ==========================================================================
+  - type: textarea
+    id: compliant-example-prose-3
+    attributes:
+      label: Compliant Example 3 - Prose (Optional)
+      description: Additional compliant example prose. Leave empty if not needed.
+      placeholder: Yet another way to comply with this guideline...
+    validations:
+      required: false
+  - type: textarea
+    id: compliant-example-code-3
+    attributes:
+      label: Compliant Example 3 - Code (Optional)
+      description: Additional compliant code example. Leave empty if not needed.
+      placeholder: |
+        ```rust
+        # fn main() {
+        // Another compliant example
+        # }
+        ```
+    validations:
+      required: false
+
+  # ==========================================================================
+  # Compliant Example 4 (Optional)
+  # ==========================================================================
+  - type: textarea
+    id: compliant-example-prose-4
+    attributes:
+      label: Compliant Example 4 - Prose (Optional)
+      description: Additional compliant example prose. Leave empty if not needed.
+      placeholder: A fourth way to comply with this guideline...
+    validations:
+      required: false
+  - type: textarea
+    id: compliant-example-code-4
+    attributes:
+      label: Compliant Example 4 - Code (Optional)
+      description: Additional compliant code example. Leave empty if not needed.
+      placeholder: |
+        ```rust
+        # fn main() {
+        // Another compliant example
+        # }
+        ```
+    validations:
+      required: false
+
+  # ==========================================================================
+  # Bibliography (Optional)
+  # ==========================================================================
+  - type: markdown
+    attributes:
+      value: |
+        ---
+        ## Bibliography (Optional)
+
+        Add references to external sources that support your guideline.
+        Use standard Markdown reference link syntax, then cite with `[CITATION-KEY]` in your text.
+        
+        **Example - defining references:**
+        ```
+        [RUST-REF-UNION]: https://doc.rust-lang.org/reference/items/unions.html "The Rust Reference | Unions"
+        [CERT-C-INT34]: https://wiki.sei.cmu.edu/confluence/x/ItcxBQ "SEI CERT C | INT34-C. Do not shift by negative bits"
+        ```
+        
+        **Example - citing in your Amplification or Rationale:**
+        ```
+        As documented in [RUST-REF-UNION], unions require unsafe access.
+        ```
+  - type: textarea
+    id: bibliography
+    attributes:
+      label: Bibliography
+      description: |
+        Use Markdown reference link syntax: `[KEY]: URL "Author | Title"`
+        
+        Citation keys must be UPPERCASE-WITH-HYPHENS, start with a letter, max 50 chars.
+      placeholder: |
+        [RUST-REF-UNION]: https://doc.rust-lang.org/reference/items/unions.html "The Rust Reference | Unions"
+        [CERT-C-INT34]: https://wiki.sei.cmu.edu/confluence/x/ItcxBQ "SEI CERT C | INT34-C. Do not shift by negative bits"
+    validations:
+      required: false