Add GOALS.md, revise contribution process, freshen up to use arewesafetycriticalyet.org

CONTRIBUTING.md

@@ -1,7 +1,122 @@
-# Contributing to a Rust Foundation Project
+# Contributing to the coding guidelines
 
-Thank you for your interest in contributing to this Rust Foundation project. 
-We are happy and excited to review and accept your pull requests.
+## Table of Contents
+
+- [Contributing to the coding guidelines](#contributing-to-the-coding-guidelines)
+  - [Table of Contents](#table-of-contents)
+  - [Contribution Workflow](#contribution-workflow)
+    - [Note on Chapter Layout](#note-on-chapter-layout)
+    - [0) Bring up the idea for discussion](#0-bring-up-the-idea-for-discussion)
+    - [1) Submit coding guideline issue](#1-submit-coding-guideline-issue)
+      - [1.1) Finding the FLS ID](#11-finding-the-fls-id)
+    - [2) Create a Draft with a Member](#2-create-a-draft-with-a-member)
+    - [3) A Pull Request is generated](#3-a-pull-request-is-generated)
+    - [4) Iterate on Feedback](#4-iterate-on-feedback)
+      - [4.1) Apply changes to the Guideline's Issue](#41-apply-changes-to-the-guidelines-issue)
+      - [4.2) Re-generate the Pull Request](#42-re-generate-the-pull-request)
+    - [5) Your Guideline gets merged](#5-your-guideline-gets-merged)
+    - [You just contributed a coding guideline!](#you-just-contributed-a-coding-guideline)
+  - [Writing a guideline locally (less typical, not recommended)](#writing-a-guideline-locally-less-typical-not-recommended)
+    - [Guideline template](#guideline-template)
+  - [Before You Begin Contributing](#before-you-begin-contributing)
+    - [Licenses](#licenses)
+    - [Code of Conduct](#code-of-conduct)
+  - [Contribution Process](#contribution-process)
+    - [Issues](#issues)
+
+## Contribution Workflow
+
+Here's a diagram of the overall process:
+
+```mermaid
+flowchart TD
+  Start(["Start"]) --> Idea["Coding Guideline Idea"]
+  Idea --> Zulip[/"(Optional)<br>0: Contributor brings <br> to discuss on Zulip"/]
+  Zulip --> CreateIssue{{"1: Contributor creates <br> issue"}}
+  CreateIssue --> Issue["Coding Guideline Issue"]
+
+  %% short local loops (no long edges)
+  S2{{"2: Review started <br> by subcommittee <br> member in <= 14 days <br><br> Contributor updates accordingly"}} --> Issue
+  Issue --> S2
+
+  Issue --> S3{{"3: Subcommitte member <br> assigns label<br>to generate PR"}} --> PR["Coding Guideline<br>Pull Request"]
+
+  S4{{"4: PR review started <br> by subcommittee member <br> in <= 14 days <br><br> Contributor discusses on PR"}} --> PR
+  PR --> S4
+
+  PR --> S5{{"5: Contributor applies <br> feedback to issue"}} --> Issue
+  Issue --> S6{{"6: Subcommittee member <br> confirms changes;<br> regenerates PR"}} --> PR
+  PR --> S7{{"7: Subcommittee member <br> approves & queues;<br>merges to main"}} --> Main[[main]]
+  Main --> End(["8: End"])
+```
+
+### Note on Chapter Layout
+
+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.
+
+### 0) Bring up the idea for discussion
+
+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.
+
+### 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).
+
+#### 1.1) Finding the FLS ID
+
+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:
+
+
+```html
+<p><span class="spec-paragraph-id" id="fls_4rhjpdu4zfqj">4.1:1</span>
+```
+
+You would then pull `fls_4rhjpdu4zfqj` to place in the FLS ID field.
+
+### 2) Create a Draft with a Member
+
+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.
+
+### 3) A Pull Request is generated
+
+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) Iterate on Feedback
+
+The generated Pull Request may attract additional feedback or simply be an easier place to suggest targeted edits.
+
+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.
+
+#### 4.1) Apply changes to the Guideline's Issue
+
+If you agree with the suggested changes, then 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.
+
+#### 4.2) Re-generate the Pull Request
+
+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.
+
+### 5) Your Guideline gets merged
+
+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.
+
+### You just 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.
 
 ## Before You Begin Contributing
 

GOALS.md

@@ -0,0 +1,54 @@
+# Goals
+
+## Elevator pitch
+
+We will make Rust coding guidelines available within this repository. The coding guidelines will additionally be deployed to an accessible location on the internet. These coding guideliens will comply with relevant standards for various safety-critical industries such as: IEC 61508, ISO 26262, and DO 178.
+
+## Detailed
+
+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 a reasonable coverage of the language.
+
+There will be an addendum which covers how various safety standards like ISO 26262 map onto the coding guidelines.
+
+## Criteria
+
+* 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 purposes: Mandatory, Required, Advisory, Disapplied. See section 5 of MISRA Compliance: 2020 for more details.
+  * 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 1. clarify which safety standards are supported 2. lower burden of users
+  * We will begin with DO 178 and ISO 26262
+  * We will begin perhaps chapter level, maybe subsection level _for now_ and may expand granularity of matrix mapping later
+* We will release the coding guidelines tagged with the versions of stable Rust that they support (e.g. `1.42`)
+* We will find or 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](https://en.wikipedia.org/wiki/Decidability_(logic)))
+* 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
+* We will produce the guidelines and a hash of their contents in a machine readable and consistent format, to make consumption simpler for tool vendors. These artifacts are:
+  * a `needs.json` containing the contents of the coding guidelines
+  * a `guidelines-ids.json` which has hashes of the guidelines' contents, which can be used to check against (and break) a tool vendor's build, until an audit is performed
+
+# Explicit non-goals
+
+* For the initial version to have complete coverage of the Rust programming language
+  * "Something" shipped to alleviate pressure at organizations is better than "nothing is available"
+  * An accepted means of delivering partially complete coding guidelines by IEC 61508 and other
+    similar safety standards is to subset the language.
+    * Language subsetting as defined in IEC 61508 and ISO 26262 may be used to prevent the usage
+      of certain language constructs which are not suitable for use in safety-critical systems.
+    * The same mechanism can be used to subset out portions of the Rust programming language for
+      which we do not yet have a sufficient degree of coverage via the coding guidelines.
+    * For a more detailed treatment, please see IEC 61508:2010-7, Annex C: "C.2.6.2 Coding standards"
+      for a breakdown in a table and "C.4.2 Language subsets" for rationale.
+      * A commented version of IEC 61508 is available [here](https://share.ansi.org/Shared%20Documents/News%20and%20Publications/Other%20Documents/IEC%2061508%20Commented%20Version.pdf) from ANSI.
+* For any version to be conflict-free with various members' or their organizations' viewpoints
+  * Members and their organizations may take different stances on how The Rust Programming Language's 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 a user may need to adjust in an internal version, which would then be downstreamed.

README.md

@@ -2,10 +2,24 @@
 
 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.
 
+## Table of Contents
+- [Building the coding guidelines](#building-the-coding-guidelines)
+   - [Running builds offline](#running-builds-offline)
+   - [Build breaking due to out-dated spec lock file](#build-breaking-due-to-out-dated-spec-lock-file)
+   - [Continuing work while on a feature branch](#continuing-work-while-on-a-feature-branch)
+   - [If you need to audit the difference](#if-you-need-to-audit-the-difference)
+- [Outline \& issue breakdown](#outline--issue-breakdown)
+- [Contribution](#contribution)
+- [Code of Conduct](#code-of-conduct)
+- [Licenses](#licenses)
+- [Other Policies](#other-policies)
+
 ## Building the coding guidelines
 
 The Safety-Critical Rust Coding Guidelines use `Sphinx` and `Sphinx-Needs` to build a rendered version of the coding guidelines, and `uv` to install and manage Python dependencies (including Sphinx itself). To simplify building the rendered version, we created a script called `make.py` that takes care of invoking Sphinx with the right flags.
@@ -42,7 +56,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:
 
@@ -55,7 +69,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:
 
@@ -101,34 +115,15 @@ 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.
 
-## Contributing to the coding guidelines
-
-See [CONTRIBUTING.md](CONTRIBUTING.md).
-
-### 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.
-
-### Guideline template
+## Outline & issue breakdown
 
-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.
-
-### Filling out the guideline
-
-Reference `src/conf.py` to see valid selections for unfilled options in the guideline template.
-
-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:
-
-```html
-<p><span class="spec-paragraph-id" id="fls_4rhjpdu4zfqj">4.1:1</span>
-```
+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.
 
-You would then pull `fls_4rhjpdu4zfqj` to place in the `:fls:` option.
+## Contributing
 
-Existing guidelines can also serve as examples on how guidelines are filled.
+Thank you for your interest in contributing to the Safety-Critical Rust Coding Guidelines!
 
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for the details on how to do so.
 
 ## [Code of Conduct][code-of-conduct]