Make steps more concrete on how to contribute.

Author: PLeVasseur

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.

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
+<p><span class="spec-paragraph-id" id="fls_4rhjpdu4zfqj">4.1:1</span>
+```
 
-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
-<p><span class="spec-paragraph-id" id="fls_4rhjpdu4zfqj">4.1:1</span>
-```
+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]