diff --git a/GOALS.md b/GOALS.md new file mode 100644 index 0000000..af10900 --- /dev/null +++ b/GOALS.md @@ -0,0 +1,59 @@ +# 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. functions, arithmetic, 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 released and tagged with the versions of stable Rust that they support (e.g. `1.42`) +* Upstream Clippy lints which will cover decidable guidelines + +## Goals obtained by discussion with Tooling Subcommittee + +* Make a label for each which _in theory_ is decidable or not +* Include for each guideline a minimum of one compliant and one non-compliant example of code, to help illustrate its exact meaning and context. +* Consider only the language reference / spec, not the tooling availability when writing the coding guidelines +* Guidelines should be evidence-based, with statistics around human error when programming Rust, to support: + 1. What guidelines are written, and + 2. Why a specific 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. + * 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..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. @@ -109,6 +111,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.