diff --git a/.github/workflows/build-guidelines.yml b/.github/workflows/build-guidelines.yml index e0e41759..59d517e2 100644 --- a/.github/workflows/build-guidelines.yml +++ b/.github/workflows/build-guidelines.yml @@ -76,3 +76,10 @@ jobs: path: build retention-days: 7 compression-level: 6 # Default compression level for a good balance of speed and size + lint_rst: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + - name: Check for typos + run: pipx run sphinx-lint src \ No newline at end of file diff --git a/src/coding-guidelines/macros.rst b/src/coding-guidelines/macros.rst index 7094d92f..9aaec25d 100644 --- a/src/coding-guidelines/macros.rst +++ b/src/coding-guidelines/macros.rst @@ -101,22 +101,22 @@ Macros :tags: reduce-human-error Functions should always be preferred over macros, except when macros provide essential functionality that functions cannot, such as variadic interfaces, compile-time code generation, or syntax extensions via custom derive and attribute macros. - + | - .. rationale:: + .. rationale:: :id: rat_M9bp23ctkzQ7 :status: draft Although the compiler reports both the macro expansion and its invocation site, diagnostics originating within macros can be more difficult to interpret than those from ordinary function or type definitions. Complex or deeply nested macros may obscure intent and hinder static analysis, increasing the risk of misinterpretation or overlooked errors during code review. - - **Debugging Complexity** + + **Debugging Complexity** - Errors point to expanded code rather than source locations, making it difficult to trace compile-time errors back to the original macro invocation. **Optimization** - + - Macros may inhibit compiler optimizations that work better with functions. - Macros act like ``#[inline(always)]`` functions, which can lead to code bloat. - They don't benefit from the compiler's inlining heuristics, missing out on selective inlining where the compiler decides when inlining is beneficial. @@ -134,7 +134,7 @@ Macros :status: draft Using a macro where a simple function would suffice, leads to hidden mutation: - + .. code-block:: rust macro_rules! increment_and_double { @@ -162,7 +162,7 @@ Macros .. code-block:: rust fn increment_and_double(x: &mut i32) -> i32 { - *x += 1; // mutation is explicit + *x += 1; // mutation is explicit *x * 2 } let mut num = 5; @@ -172,7 +172,7 @@ Macros The function version makes the mutation and borrowing explicit in its signature, improving readability, safety, and debuggability. - + .. guideline:: Shall not use Function-like Macros :id: gui_WJlWqgIxmE8P @@ -355,7 +355,7 @@ Macros Attribute macros shall neither be declared nor invoked. Prefer less powerful macros that only extend source code. - .. rationale:: + .. rationale:: :id: rat_X8uCF5yx7Mpo :status: draft @@ -366,9 +366,9 @@ Macros :status: draft Explanation of code example. - + .. code-block:: rust - + #[tokio::main] // non-compliant async fn main() { @@ -379,18 +379,18 @@ Macros :status: draft Explanation of code example. - + .. code-block:: rust - + fn example_function() { // Compliant implementation } - + .. guideline:: Do not hide unsafe blocks within macro expansions - :id: gui_FRLaMIMb4t3S - :category: required - :status: draft - :release: todo + :id: gui_FRLaMIMb4t3S + :category: required + :status: draft + :release: todo :fls: fls_4vjbkm4ceymk :decidability: todo :scope: todo @@ -398,7 +398,7 @@ Macros Description of the guideline goes here. - .. rationale:: + .. rationale:: :id: rat_WJubG7KuUDLW :status: draft diff --git a/src/coding-guidelines/types-and-traits.rst b/src/coding-guidelines/types-and-traits.rst index e44ce284..dd1109dc 100644 --- a/src/coding-guidelines/types-and-traits.rst +++ b/src/coding-guidelines/types-and-traits.rst @@ -17,7 +17,7 @@ Types and Traits :tags: numerics Code must not rely on Rust's implicit integer wrapping behavior that may occur in release - builds. Instead, explicitly handle potential overflows using the standard library's checked, + builds. Instead, explicitly handle potential overflows using the standard library's checked, saturating, or wrapping operations. .. rationale:: @@ -36,7 +36,7 @@ Types and Traits .. _overflow-checks: https://github.com/rust-lang/rust/blob/master/src/doc/rustc/src/codegen-options/index.md#overflow-checks .. _frequently requested change: https://lang-team.rust-lang.org/frequently-requested-changes.html#numeric-overflow-checking-should-be-on-by-default-even-in-release-mode - + Safety-critical software requires consistent and predictable behavior across all build configurations. Explicit handling of potential overflow conditions improves code clarity, maintainability, and reduces the risk of numerical errors in production. @@ -44,9 +44,9 @@ Types and Traits .. non_compliant_example:: :id: non_compl_ex_PO5TyFsRTlWv :status: draft - + .. code-block:: rust - + fn calculate_next_position(current: u32, velocity: u32) -> u32 { // Potential for silent overflow in release builds current + velocity @@ -55,9 +55,9 @@ Types and Traits .. compliant_example:: :id: compl_ex_WTe7GoPu5Ez0 :status: draft - + .. code-block:: rust - + fn calculate_next_position(current: u32, velocity: u32) -> u32 { // Explicitly handle potential overflow with checked addition current.checked_add(velocity).expect("Position calculation overflowed") diff --git a/src/conf.py b/src/conf.py index a656c282..fda72ec6 100644 --- a/src/conf.py +++ b/src/conf.py @@ -38,28 +38,28 @@ "directive": "guideline", "title": "Guideline", "prefix": "gui_", - "color": "#BFD8D2", + "color": "#BFD8D2", "style": "node" }, { "directive": "rationale", "title": "Rationale", "prefix": "rat_", - "color": "#DF744A", + "color": "#DF744A", "style": "node" }, { "directive": "compliant_example", "title": "Compliant Example", "prefix": "compl_ex_", - "color": "#729FCF", + "color": "#729FCF", "style": "node" }, { "directive": "non_compliant_example", "title": "Non-Compliant Example", "prefix": "non_compl_ex_", - "color": "#729FCF", + "color": "#729FCF", "style": "node" } ] diff --git a/src/process/style-guideline.rst b/src/process/style-guideline.rst index 194b89a7..c0d6bd75 100644 --- a/src/process/style-guideline.rst +++ b/src/process/style-guideline.rst @@ -39,8 +39,8 @@ We will examine each part: :scope: module :tags: numerics - Code must not rely on Rust's implicit integer wrapping behavior that occurs in release builds. - Instead, explicitly handle potential overflows using the standard library's checked, + Code must not rely on Rust's implicit integer wrapping behavior that occurs in release builds. + Instead, explicitly handle potential overflows using the standard library's checked, saturating, or wrapping operations. .. rationale:: @@ -50,7 +50,7 @@ We will examine each part: In debug builds, Rust performs runtime checks for integer overflow and will panic if detected. However, in release builds (with optimizations enabled), integer operations silently wrap around on overflow, creating potential for silent failures and security vulnerabilities. - + Safety-critical software requires consistent and predictable behavior across all build configurations. Explicit handling of potential overflow conditions improves code clarity, maintainability, and reduces the risk of numerical errors in production. @@ -58,9 +58,9 @@ We will examine each part: .. non_compliant_example:: :id: non_compl_ex_PO5TyFsRTlWv :status: draft - + .. code-block:: rust - + fn calculate_next_position(current: u32, velocity: u32) -> u32 { // Potential for silent overflow in release builds current + velocity @@ -69,9 +69,9 @@ We will examine each part: .. compliant_example:: :id: compl_ex_WTe7GoPu5Ez0 :status: draft - + .. code-block:: rust - + fn calculate_next_position(current: u32, velocity: u32) -> u32 { // Explicitly handle potential overflow with checked addition current.checked_add(velocity).expect("Position calculation overflowed") @@ -142,7 +142,7 @@ An organization or project **MAY** choose to recategorize any ``required`` guide ``advisory`` ^^^^^^^^^^^^ -These are recommendations and **SHOULD** be applied. However, the category of ``advisory`` does not mean +These are recommendations and **SHOULD** be applied. However, the category of ``advisory`` does not mean that these items can be ignored, but rather that they **SHOULD** be followed as far as reasonably practical. Formal deviation is not necessary for advisory guidelines but, if the formal deviation process is not followed, alternative arrangements **MUST** be made for documenting non-compliances. @@ -181,7 +181,7 @@ the ``status`` to ``retired``. * ``approved`` * ``retired`` -Guidelines have a lifecycle. When they are first proposed and **MUST** be marked as ``draft`` +Guidelines have a lifecycle. When they are first proposed and **MUST** be marked as ``draft`` to allow adoption and feedback to accrue. The Coding Guidelines Subcommittee **MUST** periodically review ``draft`` guidelines and either promote them to ``approved`` or demote them to ``retired``. @@ -196,8 +196,8 @@ For more, see :ref:`Guideline Lifecycle`. ``draft`` ^^^^^^^^^ -These guidelines are not yet considered in force, but are mature enough they **MAY** be enforced. -No formal deviation is required as outlined in :ref:`Compliance`, but alternative arrangements +These guidelines are not yet considered in force, but are mature enough they **MAY** be enforced. +No formal deviation is required as outlined in :ref:`Compliance`, but alternative arrangements **MUST** be made for documenting non-compliances. *Note*: ``draft`` guideline usage and feedback will help to either promote them to ``approved`` or demote @@ -339,7 +339,7 @@ require a deviation. In debug builds, Rust performs runtime checks for integer overflow and will panic if detected. However, in release builds (with optimizations enabled), integer operations silently wrap around on overflow, creating potential for silent failures and security vulnerabilities. - + Safety-critical software requires consistent and predictable behavior across all build configurations. Explicit handling of potential overflow conditions improves code clarity, maintainability, and reduces the risk of numerical errors in production. @@ -373,9 +373,9 @@ TODO(pete.levasseur) .. non_compliant_example:: :id: non_compl_ex_PO5TyFsRTlWv :status: draft - + .. code-block:: rust - + fn calculate_next_position(current: u32, velocity: u32) -> u32 { // Potential for silent overflow in release builds current + velocity @@ -384,7 +384,7 @@ TODO(pete.levasseur) ``non_compliant_example`` ``id`` -------------------------------- -A unique identifier for each ``non_compliant_example``. ``non_compliant_example`` identifiers +A unique identifier for each ``non_compliant_example``. ``non_compliant_example`` identifiers **MUST** begin with ``non_compl_ex_``. These identifiers are considered **stable** across releases and **MUST NOT** be removed. @@ -440,9 +440,9 @@ than the current guideline. .. compliant_example:: :id: compl_ex_WTe7GoPu5Ez0 :status: draft - + .. code-block:: rust - + fn calculate_next_position(current: u32, velocity: u32) -> u32 { // Explicitly handle potential overflow with checked addition current.checked_add(velocity).expect("Position calculation overflowed") @@ -451,7 +451,7 @@ than the current guideline. ``compliant_example`` ``id`` ---------------------------- -A unique identifier for each ``compliant_example``. ``compliant_example`` identifiers +A unique identifier for each ``compliant_example``. ``compliant_example`` identifiers **MUST** begin with ``compl_ex_``. These identifiers are considered **stable** across releases and **MUST NOT** be removed.