From 4f6a0470c645eeb69749c1b32bc09815b6b6696d Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Tue, 15 Jul 2025 06:25:52 +0900 Subject: [PATCH 1/2] Move goals into GOALS.md --- GOALS.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 ++++++ 2 files changed, 61 insertions(+) create mode 100644 GOALS.md diff --git a/GOALS.md b/GOALS.md new file mode 100644 index 0000000..5352f33 --- /dev/null +++ b/GOALS.md @@ -0,0 +1,55 @@ +# Overview + +## Elevator pitch + +Coding guidelines are available within this repository, potentially deployed to a website mdBook-style. + +## Detailed + +In general these coding guidelines should be a set of rules of do / do not do with examples which should cover all "general" aspects of the Rust programming language, e.g. enums, structs, traits, and so on. We can use the [FLS](https://rust-lang.github.io/fls/index.html) as a means to ensure we have reasonable coverage of the language. + +There should be an addendum which covers how various safety standards like ISO 26262 map onto the coding guidelines. + +This serves as a tracking issue which is why it's considered "XL". Work will get logged against this in smaller chunks! + +# Way of work + +## Outline & issue breakdown + +We will use the Coding Guidelines Work Items [board](https://github.com/orgs/rustfoundation/projects/1) as a means to break the work down into smaller chunks that can be tackled in a reasonable manner. + +## Contribution of existing guidelines + +We are very open to receiving contributed coding guidelines in whole or in part and wholly originally contributions based on learnings from past organizational experience using Rust in safety-critical projects. + +## Contribution of a new guideline + +A good first step is to open a new [coding guideline issue](https://github.com/rustfoundation/safety-critical-rust-coding-guidelines/issues/new?template=CODING-GUIDELINE.yml). + +# Goals + +* Coding guidelines that make a "best effort" attempt at cataloging common pieces (e.g. struct or unsafe) of the Rust programming language and how they fit into a safety-critical project + * We will use [MISRA Compliance: 2020](https://misra.org.uk/app/uploads/2021/06/MISRA-Compliance-2020.pdf) for categorization + * Includes rationale with links to parts of the Rust Project and wider Rust community for guidance + * Could later be refined according to various standards, e.g. DO 178 or ISO 26262 +* Practical recommendations on how to use this piece of the language + * May include considerations of "what" is being built, e.g. broadly speaking library software: (potentially broke down further into low-level driver code, a framework system for real-time applications, SDKs) vs application software +* Should be done in parallel with developing an addendum matrix to reduce burden of attaching these later + * We can begin with DO 178 and ISO 26262 at perhaps chapter level, maybe subsection level _for now_ and expand later +* Releases of the coding guidelines are tagged and released with versions of the stable compiler which they support +* Upstream Clippy lints which will cover decideable guidelines + +## Goals obtained by discussion with Tooling Subcommittee + +* Make a label for each which _in theory_ is decidable or not +* Include for each a minimum of one compliant and non-compliant example of code to illustrate point +* Consider only the language reference / spec, not the tooling availability when writing the coding guidelines +* Evidence-based with statistics around human error when programming Rust to support both 1. what guidelines are written and 2. why a suggestion was made +* Produce the guidelines in an artifact that's easily machine readable and consistent format to make it easier to consume by tool vendors as a baseline (e.g. multiple JSON files, one per language piece, also potentially one large JSON concatenated together) + +# Non-goals + +* For the initial version to be complete coverage of the Rust programming languages pieces + * "Something" shipped to alleviate pressure at organizations is better than "nothing available" +* For any version to be conflict-free with various members' or their organizations' viewpoints + * Members and their organizations may take different stances on how pieces of the Rust programming language should be viewed and approached. This is okay and expected. We'd like to ship something that we can obtain broad consensus on and worst case scenario there may be a section here or there which you may need to adjust in an internal version that'd downstream. diff --git a/README.md b/README.md index b7c6769..f696646 100644 --- a/README.md +++ b/README.md @@ -109,6 +109,12 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). We have the same chapter layout as the [Ferrocene Language Specification](https://spec.ferrocene.dev/) (FLS). If you would like to contribute you may find a section from the FLS of interest and then write a guideline in the corresponding chapter of these coding guidelines. +### Submit coding guideline issue + +For a new coding guideline you'd like to contribute, start with opening a [coding guideline issue](https://github.com/rustfoundation/safety-critical-rust-coding-guidelines/issues/new?template=CODING-GUIDELINE.yml). + +Once an issue has been well-developed enough it's then time to write up the guideline. + ### Guideline template We have a script `./generate-guideline-templates.py` which which assumes you're using `uv` that can be run to generate the template for a guideline with properly randomized IDs. From 863169bf2c952cfcc760a72856ba129cde48f8a7 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Tue, 15 Jul 2025 06:28:56 +0900 Subject: [PATCH 2/2] Add GOALS.md link to README.md. Update URL of deployed version to arewesafetycriticalyet.org --- GOALS.md | 2 +- README.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/GOALS.md b/GOALS.md index 5352f33..d97ee89 100644 --- a/GOALS.md +++ b/GOALS.md @@ -37,7 +37,7 @@ A good first step is to open a new [coding guideline issue](https://github.com/r * Should be done in parallel with developing an addendum matrix to reduce burden of attaching these later * We can begin with DO 178 and ISO 26262 at perhaps chapter level, maybe subsection level _for now_ and expand later * Releases of the coding guidelines are tagged and released with versions of the stable compiler which they support -* Upstream Clippy lints which will cover decideable guidelines +* Upstream Clippy lints which will cover decidable guidelines ## Goals obtained by discussion with Tooling Subcommittee diff --git a/README.md b/README.md index f696646..f1c1b4b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ Coding Guidelines for Safety Critical Rust developed by the [Safety Critical Rust Consortium][safety-critical-rust-consortium]. -[View the latest rendered guidelines online](https://rustfoundation.github.io/safety-critical-rust-coding-guidelines/) +[View the latest rendered guidelines online](https://coding-guidelines.arewesafetycriticalyet.org/) + +Check out the [coding guideline goals](GOALS.md). _Note_: Early, subject to changes.