From 881c4d86056b6475883c8dc361004ac337d11ca5 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Tue, 15 Jul 2025 06:25:52 +0900 Subject: [PATCH 01/10] 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 292f420..54a990a 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 assumes you're using `uv` that can be run to generate the template for a guideline with properly randomized IDs. From 9407d2866643454b7d713f24640b76a532ef7fb7 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Tue, 15 Jul 2025 06:28:56 +0900 Subject: [PATCH 02/10] 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 54a990a..20d8cfe 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. From 5ae93b50f2d98ac2b4be5d29b6239a854f74dfe2 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Tue, 12 Aug 2025 22:10:45 -0400 Subject: [PATCH 03/10] Update GOALS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Félix Fischer --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index d97ee89..dbb62c4 100644 --- a/GOALS.md +++ b/GOALS.md @@ -28,7 +28,7 @@ A good first step is to open a new [coding guideline issue](https://github.com/r # 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 +* 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 From 79b20ab3dfe0bc2cc9168760df03000347378764 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Tue, 12 Aug 2025 22:11:00 -0400 Subject: [PATCH 04/10] Update GOALS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Félix Fischer --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index dbb62c4..976a263 100644 --- a/GOALS.md +++ b/GOALS.md @@ -36,7 +36,7 @@ A good first step is to open a new [coding guideline issue](https://github.com/r * 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 +* 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 From 231fc26b60a95a9160bb839f9222cb27b13d9bb3 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Tue, 12 Aug 2025 22:11:15 -0400 Subject: [PATCH 05/10] Update GOALS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Félix Fischer --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 976a263..8e3f1d4 100644 --- a/GOALS.md +++ b/GOALS.md @@ -42,7 +42,7 @@ A good first step is to open a new [coding guideline issue](https://github.com/r ## 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 +* 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 * 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) From b15597d4ebbf86b9d53f0c9836526f700009cdfb Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Tue, 12 Aug 2025 22:11:26 -0400 Subject: [PATCH 06/10] Update GOALS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Félix Fischer --- GOALS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 8e3f1d4..8578a75 100644 --- a/GOALS.md +++ b/GOALS.md @@ -44,7 +44,9 @@ A good first step is to open a new [coding guideline issue](https://github.com/r * 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 -* 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 +* 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 From 4f0f9fe38aa5d16cd7e4f50e98dfc26122640c03 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Tue, 12 Aug 2025 22:11:56 -0400 Subject: [PATCH 07/10] Update GOALS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Félix Fischer --- GOALS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 8578a75..af10900 100644 --- a/GOALS.md +++ b/GOALS.md @@ -54,4 +54,6 @@ A good first step is to open a new [coding guideline issue](https://github.com/r * 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. + * 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. From 7c89bd918d11842778e662d6f7fd9542bc02cf6e Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Wed, 17 Sep 2025 06:21:34 +0900 Subject: [PATCH 08/10] Make steps more concrete on how to contribute. --- GOALS.md | 67 ++++++++++++++++++++--------------------------------- README.md | 69 ++++++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 80 insertions(+), 56 deletions(-) diff --git a/GOALS.md b/GOALS.md index af10900..38793c9 100644 --- a/GOALS.md +++ b/GOALS.md @@ -1,59 +1,42 @@ -# Overview +# Goals ## Elevator pitch -Coding guidelines are available within this repository, potentially deployed to a website mdBook-style. +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. ## 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 +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. -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. +There will be an addendum which covers how various safety standards like ISO 26262 map onto the coding guidelines. -## 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 +## Criteria -* 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 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 * 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: + * We include a rationale with links to parts of the Rust Project and wider Rust community for guidance + * We will include linkage where appropriate to to various standards, e.g. CERT C, MISRA C, DO 178, ISO 26262 + * We will include practical recommendations on how to use this piece of the language using compliant and non-compliant examples +* We will develop an addendum matrix to reduce burden of attaching these later + * We will begin with DO 178 and ISO 26262 at perhaps chapter level, maybe subsection level _for now_ and expand later +* We will release the coding guidelines tagged with the versions of stable Rust that they support (e.g. `1.42`) +* We will create Clippy lints which will cover decidable guidelines + +### Criteria obtained by discussion with Tooling Subcommittee + +* We will affix a label for each guideline, which describes whether said guideline is decidable or not (in the theory of computation sense) +* 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. +* We will consider only the language reference / spec, not the tooling availability when writing the coding guidelines +* We aim to produce evidence-based guidelines, 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) +* 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) -# Non-goals +# Explicit 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 the initial version to be complete coverage of the Rust programming language + * "Something" shipped to alleviate pressure at organizations is better than "nothing is available" even if we have to heavily subset the language * 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**. + * Members and their organizations may take different stances on how Rust programming language constructs 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 20d8cfe..8fd163b 100644 --- a/README.md +++ b/README.md @@ -103,40 +103,81 @@ Once you have completed the above steps, you will now update the local copy of t Open a new PR with only the changes necessary to rationalize the guidelines with the new FLS text. +## 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. + ## Contributing to the coding guidelines See [CONTRIBUTING.md](CONTRIBUTING.md). -### Chapter layout mirrors Ferrocene Language Specification +### Have an idea? Want to discuss it? + +While not mandatory, sometimes you'd like to check into the feasiblity of a guideline or discuss it with others to ensure it's not overlapping an existing guideline. Feel free to drop by the Safety-Critical Rust Consortium's Zulip stream: [here](https://rust-lang.zulipchat.com/#narrow/channel/445688-safety-critical-consortium). Please open a new topic per coding guideline you'd like to discuss. + +### Preamble: chapter layout mirrors Ferrocene Language Specification 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 +### 1. 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. +#### 1.a Finding the FLS ID -### Guideline template +Note that the FLS ID should be filled according to the FLS paragraph ID for which the guideline is covering. One way to go about finding this is to inspect the page using your web browser. You'll be looking for something like: -We have a script `./generate_guideline_templates.py` which assumes you're using `uv` that can be run to generate the template for a guideline with properly randomized IDs. +```html +

4.1:1 +``` -You can the copy and paste this guideline from the command line into the correct chapter. +You would then pull `fls_4rhjpdu4zfqj` to place in the FLS ID field. -### Filling out the guideline +### 2. A subcommittee member reviews the coding guideline issue, works with you the contributor -Reference `src/conf.py` to see valid selections for unfilled options in the guideline template. +A member of the Coding Guidelines Subcommittee should get you a first review with some feedback within 14 days of submission. You'll work with one or more members to flesh out the concept and ensure the guideline is well prepared. -Note that the `:fls:` option should be filled according to the FLS paragraph ID for which the guideline is covering. One way to go about finding this is to inspect the page using your web browser. You'll be looking for something like: +### 3. A pull request is generated from the coding guideline issue -```html -

4.1:1 -``` +Once an issue has been well-developed enough, a subcommittee member will mark the issue with the label `sign-off: create pr from issue` to generate a pull request. You will see a GitHub Workflow trigger and a pull request will be created momentarily. + +### 4. Contributor responds to feedback given on pull request -You would then pull `fls_4rhjpdu4zfqj` to place in the `:fls:` option. +The generated pull request may attract additional feedback or simply be an easier place to suggest targeted edits. -Existing guidelines can also serve as examples on how guidelines are filled. +As the contributor of the coding guideline and opener of the issue, you'll respond to comments, discuss, all the normal things on the pull request. +### 5. Contributor applies updates to coding guidelines issue + +If you agree with the suggested changes, rather than making changes on the opened pull request, you will return to the original issue you opened via the coding guideline issue template and make the updates there. + +### 6. A subcommittee member generates new pull request contents from coding guidelines issue + +When you have completed all feedback given to you, ping one of the subcommittee members. They will then remove and affix the label `sign-off: create pr from issue` to push the changes made in the issue to the already opened pull request. + +### 7. A subcommittee member merges the coding guideline pull request + +Once the coding guideline contents have passed review, a subcommittee member will approve the pull request, and put it on the merge queue to be merged. + +### 8. You contributed a coding guideline + +That's it! + +## Writing a guideline locally (less typical, not recommended) + +While it is possible to create guidelines locally and open pull requests yourself, we encourage contributors to make use of the process described above since it handled some of the fiddly details for you as a guideline writer. + +Generally speaking, pull requests for guidelines which do not follow the issue to pull request workflow described above will be closed with a recommendation to follow the workflow. + +### Guideline template + +We have a script `./generate_guideline_templates.py` which assumes you're using `uv` that can be run to generate the template for a guideline with properly randomized IDs. + +You can the copy and paste this guideline from the command line into the correct chapter. ## [Code of Conduct][code-of-conduct] From 8a09b722b674a3287939a8e4018e39c5a23321a0 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Wed, 17 Sep 2025 07:30:37 +0900 Subject: [PATCH 09/10] Add diagram --- README.md | 44 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 8fd163b..1868009 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ A machine-parseable artifact will be available at `build/html/needs.json`. (ToDo A record with checksums of the contents is available at `build/html/guidelines-ids.json`. Users of the coding guidelines can reference this file to determine if there have been changes to coding guidelines contents they should be aware of. -## Running builds offline +### Running builds offline If you're working without internet access or want to avoid reaching out to remote resources, you can pass the `--offline` flag: @@ -57,7 +57,7 @@ This prevents the build system from attempting to fetch remote resources, such a It is recommended to use `--offline` if you are running `make.py` frequently during development. The builder fetches data from [the Ferrocene Language Specification website](https://spec.ferrocene.dev/paragraph-ids.json), which may rate-limit repeated requests—leading to delays or failed builds. Using `--offline` can significantly improve build speed and avoid unnecessary network issues during iterative work. -## Build breaking due to out-dated spec lock file +### Build breaking due to out-dated spec lock file It's a fairly common occurrence for the build to break due to an out of date spec lock file, located at: @@ -107,15 +107,45 @@ Open a new PR with only the changes necessary to rationalize the guidelines with 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. - ## Contributing to the coding guidelines See [CONTRIBUTING.md](CONTRIBUTING.md). -### Have an idea? Want to discuss it? +### Diagram for contribution workflow + +```mermaid +flowchart TD + Start(["Start"]) + CodingGuidelineIdea["Coding Guideline Idea"] + DiscussOnZulip[/"(Optional)
Discuss on Zulip"/] + CodingGuidelineIssue["Coding Guideline Issue"] + CodingGuidelinePR["Coding Guideline
Pull Request"] + Main[[main]] + End(["End"]) + + %% new: small local hop nodes (no self-loops) + IssueReview{{"2: subcommittee member
reviews within 14 days

contributor updates issue"}} + PRReview{{"4: subcommittee members
review within 14 days

contributor discusses on
PR as needed"}} + + Start -- contributor thinks of idea --> CodingGuidelineIdea + CodingGuidelineIdea -- 0: optionally post on Zulip --> DiscussOnZulip + DiscussOnZulip -- 1: contributor creates
coding guideline issue --> CodingGuidelineIssue + + %% replace Issue self-loop + CodingGuidelineIssue --> IssueReview --> CodingGuidelineIssue + + CodingGuidelineIssue -- 3: subcommittee member
assigns label to
generate pull request --> CodingGuidelinePR + + %% replace PR self-loop + CodingGuidelinePR --> PRReview --> CodingGuidelinePR + + CodingGuidelinePR -- 5: contributor applies
feedback to coding
guideline issue --> CodingGuidelineIssue + CodingGuidelineIssue -- 6: subcomittee member
confirms changes;
assigns label to
regenerate PR --> CodingGuidelinePR + CodingGuidelinePR -- 7: subcommittee member
approves, adds
to merge queue;
gets merged to main --> Main + Main -- process complete --> End +``` + +### 0. Have an idea for a coding guideline? Want to discuss it? While not mandatory, sometimes you'd like to check into the feasiblity of a guideline or discuss it with others to ensure it's not overlapping an existing guideline. Feel free to drop by the Safety-Critical Rust Consortium's Zulip stream: [here](https://rust-lang.zulipchat.com/#narrow/channel/445688-safety-critical-consortium). Please open a new topic per coding guideline you'd like to discuss. From ff367d14930503c474de969c5ba18c09b7f1ecba Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Wed, 17 Sep 2025 07:51:44 +0900 Subject: [PATCH 10/10] Update contribution workflow diagram --- README.md | 46 ++++++++++++++++++---------------------------- 1 file changed, 18 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 1868009..0d0999e 100644 --- a/README.md +++ b/README.md @@ -115,34 +115,24 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). ```mermaid flowchart TD - Start(["Start"]) - CodingGuidelineIdea["Coding Guideline Idea"] - DiscussOnZulip[/"(Optional)
Discuss on Zulip"/] - CodingGuidelineIssue["Coding Guideline Issue"] - CodingGuidelinePR["Coding Guideline
Pull Request"] - Main[[main]] - End(["End"]) - - %% new: small local hop nodes (no self-loops) - IssueReview{{"2: subcommittee member
reviews within 14 days

contributor updates issue"}} - PRReview{{"4: subcommittee members
review within 14 days

contributor discusses on
PR as needed"}} - - Start -- contributor thinks of idea --> CodingGuidelineIdea - CodingGuidelineIdea -- 0: optionally post on Zulip --> DiscussOnZulip - DiscussOnZulip -- 1: contributor creates
coding guideline issue --> CodingGuidelineIssue - - %% replace Issue self-loop - CodingGuidelineIssue --> IssueReview --> CodingGuidelineIssue - - CodingGuidelineIssue -- 3: subcommittee member
assigns label to
generate pull request --> CodingGuidelinePR - - %% replace PR self-loop - CodingGuidelinePR --> PRReview --> CodingGuidelinePR - - CodingGuidelinePR -- 5: contributor applies
feedback to coding
guideline issue --> CodingGuidelineIssue - CodingGuidelineIssue -- 6: subcomittee member
confirms changes;
assigns label to
regenerate PR --> CodingGuidelinePR - CodingGuidelinePR -- 7: subcommittee member
approves, adds
to merge queue;
gets merged to main --> Main - Main -- process complete --> End + Start(["Start"]) --> Idea["Coding Guideline Idea"] + Idea --> Zulip[/"(Optional)
0: Contributor brings
to discuss on Zulip"/] + Zulip --> CreateIssue{{"1: Contributor creates
issue"}} + CreateIssue --> Issue["Coding Guideline Issue"] + + %% short local loops (no long edges) + S2{{"2: Review started
by subcommittee
member in <= 14 days

Contributor updates accordingly"}} --> Issue + Issue --> S2 + + Issue --> S3{{"3: Subcommitte member
assigns label
to generate PR"}} --> PR["Coding Guideline
Pull Request"] + + S4{{"4: PR review started
by subcommittee member
in <= 14 days

Contributor discusses on PR"}} --> PR + PR --> S4 + + PR --> S5{{"5: Contributor applies
feedback to issue"}} --> Issue + Issue --> S6{{"6: Subcommittee member
confirms changes;
regenerates PR"}} --> PR + PR --> S7{{"7: Subcommittee member
approves & queues;
merges to main"}} --> Main[[main]] + Main --> End(["8: End"]) ``` ### 0. Have an idea for a coding guideline? Want to discuss it?