Rework the guideline description to remove the incorrect claim that a…

.github/ISSUE_TEMPLATE/CODING-GUIDELINE.yml

@@ -0,0 +1,178 @@
+name: Coding Guideline
+description: File a coding guideline of interest
+title: "[Coding Guideline]: "
+labels: ["coding guideline"]
+assignees:
+  - PLeVasseur
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filling out a coding guideline!
+  - type: dropdown
+    id: chapter
+    attributes:
+      label: Chapter
+      description: Which chapter does this fall under?
+      options:
+        - Associated Items
+        - Attributes
+        - Concurrency
+        - Entities and Resolution
+        - Exceptions and Errors
+        - Expressions
+        - FFI
+        - Functions
+        - Generics
+        - Implementations
+        - Inline Assembly
+        - Macros
+        - Ownership and Destruction
+        - Patterns
+        - Program Structure and Compilation
+        - Statements
+        - Types and Traits
+        - Unsafety
+        - Values
+    validations:
+      required: true
+  - type: input
+    id: title
+    attributes:
+      label: Guideline Title
+      description: The title of a guideline. Should be punchy and short. Write an Amplification to expand!
+      placeholder: We shall not allow `foo` when `bar`
+    validations:
+      required: true
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      description: Mandatory - required, no deviation possible. Required - required, deviation possible for each instance. Advisory - suggested, deviation possible to remove requirement for project-wide. Disapplied - need not be applied, very optional. Suggest using Mandatory very sparingly, if in doubt submit as Disapplied.
+      multiple: true
+      options:
+        - Mandatory
+        - Required
+        - Advisory
+        - Disapplied
+    validations:
+      required: true
+  - type: dropdown
+    id: status
+    attributes:
+      label: Status
+      description: The Status when first submitted must always be Draft. Status can be updated over time to Approved and/or Retired.
+      options:
+        - Draft
+    validations:
+      required: true
+  - type: input
+    id: release-begin
+    attributes:
+      label: Release Begin
+      description: First Rust compiler release this guideline is applicable to. If unsure enter "unclear".
+      placeholder: 1.3.0
+    validations:
+      required: true
+  - type: input
+    id: release-end
+    attributes:
+      label: Release End
+      description: Last Rust compiler release this guideline is applicable to. If unsure enter "unclear". If still valid enter "latest".
+      placeholder: 1.79.0
+    validations:
+      required: true
+  - type: input
+    id: fls-id
+    attributes:
+      label: FLS Paragraph ID
+      description: The Paragraph ID from the FLS corresponding to what this Guideline covers. Easiest way to obtain this is to navigate to the [FLS](https://rust-lang.github.io/fls), right click a section ID (e.g. `4.2:2`), inspect, and then find it in the pane which opens in your browser.
+      placeholder: fls_69zyas59o8ff
+    validations:
+      required: true
+  - type: dropdown
+    id: decidability
+    attributes:
+      label: Decidability
+      description: Decidable - This guideline can be automatically checked with tooling. Undecidable - This guideline can not be automatically checked with tooling.
+      options:
+        - Decidable
+        - Undecidable
+    validations:
+      required: true
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: Module - This guideline can be checked at the module level. Crate - This guideline can be checked at the crate level. System - This guideline must be checked alongside the entire source. If unsure, choose "System" as it's the most strict and will likely be revisited.
+      multiple: true
+      options:
+        - Module
+        - Crate
+        - System
+    validations:
+      required: true
+  - type: textarea
+    id: tags
+    attributes:
+      label: Tags
+      description: Tags describing the issue this Coding Guideline is attempting to prevent. Submit as comma-separated value list. Submit at least one tag.
+      placeholder: numerics, reduce-human-error
+    validations:
+      required: true
+  - type: textarea
+    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`
+    validations:
+      required: false
+  - type: textarea
+    id: exceptions
+    attributes:
+      label: Exception(s)
+      description: An Exception is a chance to specify conditions under which this Guideline does not apply. Zero or more may be supplied.
+      placeholder: When you are `hoge`-ing, this Guideline does not apply.
+    validations:
+      required: false
+  - type: textarea
+    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`. ...
+    validations:
+      required: true
+  - type: textarea
+    id: non-compliant-example-prose
+    attributes:
+      label: Non-Compliant Example - 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
+    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() { /* ... */ }
+    validations:
+      required: true
+  - type: textarea
+    id: compliant-example-prose
+    attributes:
+      label: Compliant Example - 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
+    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() { /* ... */ }
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.github/advanced-issue-labeler.yml

@@ -0,0 +1,75 @@
+policy:
+  - section:
+      - id: [chapter]
+        block-list: ['None', 'Other']
+        label:
+          - name: 'chapter: associated-items'
+            keys: ['Associated Items']
+          - name: 'chapter: attributes'
+            keys: ['Attributes']
+          - name: 'chapter: concurrency'
+            keys: ['Concurrency']
+          - name: 'chapter: entities-and-resolution'
+            keys: ['Entities and Resolution']
+          - name: 'chapter: exceptions-and-errors'
+            keys: ['Exceptions and Errors']
+          - name: 'chapter: expressions'
+            keys: ['Expressions']
+          - name: 'chapter: ffi'
+            keys: ['FFI']
+          - name: 'chapter: functions'
+            keys: ['Functions']
+          - name: 'chapter: generics'
+            keys: ['Generics']
+          - name: 'chapter: implementations'
+            keys: ['Implementations']
+          - name: 'chapter: inline-assembly'
+            keys: ['Inline Assembly']
+          - name: 'chapter: macros'
+            keys: ['Macros']
+          - name: 'chapter: ownership-and-destruction'
+            keys: ['Ownership and Destruction']
+          - name: 'chapter: patterns'
+            keys: ['Patterns']
+          - name: 'chapter: program-structure-and-compilation'
+            keys: ['Program Structure and Compilation']
+          - name: 'chapter: statements'
+            keys: ['Statements']
+          - name: 'chapter: types-and-traits'
+            keys: ['Types and Traits']
+          - name: 'chapter: unsafety'
+            keys: ['Unsafety']
+          - name: 'chapter: values'
+            keys: ['Values']
+      - id: [category]
+        block-list: ['None', 'Other']
+        label:
+          - name: 'category: mandatory'
+            keys: ['Mandatory']
+          - name: 'category: required'
+            keys: ['Required']
+          - name: 'category: advisory'
+            keys: ['Advisory']
+          - name: 'category: disapplied'
+            keys: ['Disapplied']
+      - id: [status]
+        block-list: ['None', 'Other', 'Approved', 'Retired']
+        label:
+          - name: 'status: draft'
+            keys: ['Draft']
+      - id: [decidability]
+        block-list: ['None', 'Other']
+        label:
+          - name: 'decidability: decidable'
+            keys: ['Decidable']
+          - name: 'decidability: undecidable'
+            keys: ['Undecidable']
+      - id: [scope]
+        block-list: ['None', 'Other']
+        label:
+          - name: 'scope: module'
+            keys: ['Module']
+          - name: 'scope: crate'
+            keys: ['Crate']
+          - name: 'scope: system'
+            keys: ['System']

.github/workflows/coding-guideline-issue-labeler.yml

@@ -0,0 +1,30 @@
+name: Coding Guideline Issue Labeler
+on:
+  issues:
+    types: [ opened ]
+
+permissions:
+  contents: read
+
+jobs:
+  label-component:
+    runs-on: ubuntu-latest
+
+    permissions:
+      # required for all workflows
+      issues: write
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Parse issue form
+        uses: stefanbuck/github-issue-parser@v3
+        id: issue-parser
+        with:
+          template-path: .github/ISSUE_TEMPLATE/CODING-GUIDELINE.yml
+
+      - name: Set labels based on fields
+        uses: redhat-plumbers-in-action/advanced-issue-labeler@v2
+        with:
+          issue-form: ${{ steps.issue-parser.outputs.jsonString }}
+          token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -10,6 +10,8 @@ _Note_: Early, subject to changes.
 
 The Safety-Critical Rust Coding Guidelines use `Sphinx` and `Sphinx-Needs` to build a rendered version of the coding guidelines, and `uv` to install and manage Python dependencies (including Sphinx itself). To simplify building the rendered version, we created a script called `make.py` that takes care of invoking Sphinx with the right flags.
 
+If you still need to install `uv` you can follow the [steps outlined](https://docs.astral.sh/uv/getting-started/installation/) on Astral's website.
+
 You can build the rendered version by running:
 
 On Linux-like systems:

builder/build_cli.py

@@ -28,7 +28,7 @@ def build_docs(
     serve: bool,
     debug: bool,
     offline: bool,
-    spec_lock_consistency_check: bool
+    spec_lock_consistency_check: bool,
 ) -> Path:
     """
     Builds the Sphinx documentation with the specified options.
@@ -70,10 +70,13 @@ def build_docs(
         conf_opt_values.append("enable_spec_lock_consistency=0")
     if offline:  
         conf_opt_values.append("offline=1")
+    if debug:  
+        conf_opt_values.append("debug=1")
+
     # Only add the --define argument if there are options to define
     if conf_opt_values:
-        args.append("--define")
         for opt in conf_opt_values:
+            args.append("--define") # each option needs its own --define
             args.append(opt)
 
     if serve:
@@ -172,6 +175,12 @@ def main(root):
     group.add_argument(
         "--xml", help="Generate Sphinx XML rather than HTML", action="store_true"
     )
+    group.add_argument(
+        "-v",
+        "--verbose",
+        help="Debug mode for the extensions, showing exceptions",
+        action="store_true",
+    )
     group.add_argument(
         "--debug",
         help="Debug mode for the extensions, showing exceptions",
@@ -183,6 +192,6 @@ def main(root):
         update_spec_lockfile(SPEC_CHECKSUM_URL, root / "src" / SPEC_LOCKFILE)
 
     rendered = build_docs(
-        root, "xml" if args.xml else "html", args.clear, args.serve, args.debug, args.offline, not args.ignore_spec_lock_diff
+        root, "xml" if args.xml else "html", args.clear, args.serve, args.debug, args.offline, not args.ignore_spec_lock_diff, 
     )