|
1 | | -# Overview |
| 1 | +# Goals |
2 | 2 |
|
3 | 3 | ## Elevator pitch |
4 | 4 |
|
5 | | -Coding guidelines are available within this repository, potentially deployed to a website mdBook-style. |
| 5 | +We will make Rust coding guidelines are available within this repository, deployed to an accessible location on the internet which comply with relevant standards for various safety-critical industries such as: IEC 61508, ISO 26262, and DO 178. |
6 | 6 |
|
7 | 7 | ## Detailed |
8 | 8 |
|
9 | | -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. |
10 | | - |
11 | | -There should be an addendum which covers how various safety standards like ISO 26262 map onto the coding guidelines. |
12 | | - |
13 | | -This serves as a tracking issue which is why it's considered "XL". Work will get logged against this in smaller chunks! |
14 | | - |
15 | | -# Way of work |
16 | | - |
17 | | -## Outline & issue breakdown |
| 9 | +In general these coding guidelines will 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 will use the [FLS](https://rust-lang.github.io/fls/index.html) as a means to ensure we have reasonable coverage of the language. |
18 | 10 |
|
19 | | -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. |
| 11 | +There will be an addendum which covers how various safety standards like ISO 26262 map onto the coding guidelines. |
20 | 12 |
|
21 | | -## Contribution of existing guidelines |
22 | | - |
23 | | -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. |
24 | | - |
25 | | -## Contribution of a new guideline |
26 | | - |
27 | | -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). |
28 | | - |
29 | | -# Goals |
| 13 | +## Criteria |
30 | 14 |
|
31 | | -* 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 |
| 15 | +* We produce 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 |
32 | 16 | * We will use [MISRA Compliance: 2020](https://misra.org.uk/app/uploads/2021/06/MISRA-Compliance-2020.pdf) for categorization |
33 | | - * Includes rationale with links to parts of the Rust Project and wider Rust community for guidance |
34 | | - * Could later be refined according to various standards, e.g. DO 178 or ISO 26262 |
35 | | -* Practical recommendations on how to use this piece of the language |
36 | | - * 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 |
37 | | -* Should be done in parallel with developing an addendum matrix to reduce burden of attaching these later |
38 | | - * We can begin with DO 178 and ISO 26262 at perhaps chapter level, maybe subsection level _for now_ and expand later |
39 | | -* Releases of the coding guidelines are released and tagged with the versions of stable Rust that they support (e.g. `1.42`) |
40 | | -* Upstream Clippy lints which will cover decidable guidelines |
41 | | - |
42 | | -## Goals obtained by discussion with Tooling Subcommittee |
43 | | - |
44 | | -* Make a label for each which _in theory_ is decidable or not |
45 | | -* Include for each guideline a minimum of one compliant and one non-compliant example of code, to help illustrate its exact meaning and context. |
46 | | -* Consider only the language reference / spec, not the tooling availability when writing the coding guidelines |
47 | | -* Guidelines should be evidence-based, with statistics around human error when programming Rust, to support: |
| 17 | + * We include a rationale with links to parts of the Rust Project and wider Rust community for guidance |
| 18 | + * We will include linkage where appropriate to to various standards, e.g. CERT C, MISRA C, DO 178, ISO 26262 |
| 19 | + * We will include practical recommendations on how to use this piece of the language using compliant and non-compliant examples |
| 20 | +* We will develop an addendum matrix to reduce burden of attaching these later |
| 21 | + * We will begin with DO 178 and ISO 26262 at perhaps chapter level, maybe subsection level _for now_ and expand later |
| 22 | +* We will release the coding guidelines tagged with the versions of stable Rust that they support (e.g. `1.42`) |
| 23 | +* We will create Clippy lints which will cover decidable guidelines |
| 24 | + |
| 25 | +### Criteria obtained by discussion with Tooling Subcommittee |
| 26 | + |
| 27 | +* We will affix a label for each guideline, which describes whether said guideline is decidable or not (in the theory of computation sense) |
| 28 | +* We will include for each guideline a minimum of one compliant and one non-compliant example of code, to help illustrate its exact meaning and context. |
| 29 | +* We will consider only the language reference / spec, not the tooling availability when writing the coding guidelines |
| 30 | +* We aim to produce evidence-based guidelines, with statistics around human error when programming Rust, to support: |
48 | 31 | 1. What guidelines are written, and |
49 | 32 | 2. Why a specific suggestion was made |
50 | | -* 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) |
| 33 | +* We will 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) |
51 | 34 |
|
52 | | -# Non-goals |
| 35 | +# Explicit non-goals |
53 | 36 |
|
54 | | -* For the initial version to be complete coverage of the Rust programming languages pieces |
55 | | - * "Something" shipped to alleviate pressure at organizations is better than "nothing available" |
| 37 | +* For the initial version to be complete coverage of the Rust programming language |
| 38 | + * "Something" shipped to alleviate pressure at organizations is better than "nothing is available" even if we have to heavily subset the language |
56 | 39 | * For any version to be conflict-free with various members' or their organizations' viewpoints |
57 | | - * 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**. |
| 40 | + * Members and their organizations may take different stances on how Rust programming language constructs should be viewed and approached. This is **okay and expected**. |
58 | 41 | * We'd like to ship something that we can obtain broad consensus on. |
59 | 42 | * Worst case scenario: there may be a section here or there which you may need to adjust in an internal version that'd downstream. |
0 commit comments