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

CONTRIBUTING.md

@@ -1,8 +1,125 @@
-# Contributing to a Rust Foundation Project
+# Contributing
+
+## Contributing to a Rust Foundation Project
 
 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)
+   - [Diagram for contribution workflow](#diagram-for-contribution-workflow)
+   - [0. Have an idea for a coding guideline? Want to discuss it?](#0-have-an-idea-for-a-coding-guideline-want-to-discuss-it)
+   - [Preamble: chapter layout mirrors Ferrocene Language Specification](#preamble-chapter-layout-mirrors-ferrocene-language-specification)
+   - [1. Submit coding guideline issue](#1-submit-coding-guideline-issue)
+   - [1.a Finding the FLS ID](#1a-finding-the-fls-id)
+   - [2. A subcommittee member reviews the coding guideline issue, works with you the contributor](#2-a-subcommittee-member-reviews-the-coding-guideline-issue-works-with-you-the-contributor)
+   - [3. A pull request is generated from the coding guideline issue](#3-a-pull-request-is-generated-from-the-coding-guideline-issue)
+   - [4. Contributor responds to feedback given on pull request](#4-contributor-responds-to-feedback-given-on-pull-request)
+   - [5. Contributor applies updates to coding guidelines issue](#5-contributor-applies-updates-to-coding-guidelines-issue)
+   - [6. A subcommittee member generates new pull request contents from coding guidelines issue](#6-a-subcommittee-member-generates-new-pull-request-contents-from-coding-guidelines-issue)
+   - [7. A subcommittee member merges the coding guideline pull request](#7-a-subcommittee-member-merges-the-coding-guideline-pull-request)
+   - [8. You contributed a coding guideline](#8-you-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)
+
+## Contributing to the coding guidelines
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Diagram for contribution workflow
+
+```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"])
+```
+
+### 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.
+
+### 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.
+
+### 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.a 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. A subcommittee member reviews the coding guideline issue, works with you the contributor
+
+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 from the coding guideline issue
+
+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
+
+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.
+
+### 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.
+
 ## Before You Begin Contributing
 
 ### Licenses

GOALS.md

@@ -0,0 +1,44 @@
+# 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
+  * 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 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 in an artifact that's easily machine readable and consistent format to make it easier to consume by tool vendors to some minimal viable artifact.
+  * 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 vendors build until 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" 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 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]