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

[PLeVasseur]

Closes #145

[netlify]

❌ Deploy Preview for scrc-coding-guidelines failed.

Name	Link
🔨 Latest commit	d20616f
🔍 Latest deploy log	https://app.netlify.com/projects/scrc-coding-guidelines/deploys/68e41bda896a740008558fce

[felix91gr]

@PLeVasseur do you want me to take a look at this? :)

[PLeVasseur]

That'd be very kind of you ;D

[felix91gr]

I hope you're ready for many comments <3

[felix91gr]

Suggestions are now in place ^^

[felix91gr]

Which part of the MISRA Compliance: 2020 document are we using? (the pdf is 39 pages long)

[PLeVasseur]

scary voice: the whole thing!!

But seriously, @AlexCeleste may be better equipped to tell us if we need cite a page range or the entire document.

[felix91gr]

@PLeVasseur she said at some point that her Github notification stream is untenable; if you want her to look at something in the repo, it's best to send her a DM on Zulip.

Imma FWD this one to her :)

[felix91gr]

Long diffs. My bad.

Also I really like how the Contributing document is shaping up!

I hope my suggestions make sense x3

[felix91gr]

Suggested change

	# 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
	```suggestion
	# Contributing to the coding guidelines
	## 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:

This is part 1 of... 2 or 3? I tried to add a single suggestion, but it seems like Github can't deal properly with codeblocks inside of suggestions. The mermaid code block's ending marks were being used to end my suggestion block. Silly Github XD

[felix91gr]

Suggested change

	### 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:
	### 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:

Part 2 of 3 (I hope it's 3). The explanation comes with the last one!

[felix91gr]

Suggested change

	### 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!
	### 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!

Yay part 3 of 3!

Sorry for the very large diffs... x3

The main change is on how to present the steps. I felt the names were too long and that the document was a bit disorienting to read. I also changed the punctuation for parenthesis and other such details because I felt they were a bit more comfortable to read that way.

Some steps were more like a large step with substeps (like the 4th, 5th and 6th steps), and I combined those to make it clearer that it's an overarching process with substeps.

I deleted the link to CONTRIBUTING.md because we're already reading it hehe~

And I deleted or moved a few headings that felt a bit redundant.

Oh, btw, I also deleted that thing about the Rust Foundation. It felt to me like it broke the flow a little bit, but if we're obligated to have it in, then... oh well, let's add it back I guess x3

Here's the original:

## 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.

[felix91gr]

Here, do you mean that we will...

1. Develop an addendum matrix to help reduce the burden of later attaching these guidelines?,
2. or do you mean that we will... develop an addendum matrix later, to reduce the burden of attaching these guidelines?

I hope that makes sense. I read it and I'm not 100% sure which of those we mean.

[felix91gr]

This one also feels a bit ambiguous. Are we intending to...

1. Begin with DO 178 and ISO 26262 for now and expand upon others later?, or
2. are we intending to cover those two, beginning at either their chapter level or their subsection level, and if we begin at the latter, then we intend to expand towards the chapter level later?

I hope that makes sense as well. This one line feels a bit loose in the context of everything else.

[felix91gr]

Suggested change

	* 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.
	* We will produce the guidelines in an artifact that's easily machine readable and of a consistent format, to make it easier to consume by tool vendors to some minimal viable artifact.

This one is hard to parse. I assumed there's a missing "of a" and a missing comma in the middle.

But I'm still not 100% sure what we mean here.

1. An artifact that's easily machine readable, got it, perfect.
2. Of a consistent format, nice.
3. (1) and (2) are there so that these are easier to consume by tool vendors. Awesome.
4. ... but then we say "to some minimal viable artifact". Maybe it was "to some minimally viable artifact", but I'm still not sure what that means in the context of everything else.

Maybe this needs to be split into multiple sentences? Maybe multiple bullet points. Whatever we may need to express what we mean to say here, is good :3

[felix91gr]

Suggested change

	* 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
	* 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

This one was hard to parse as well. I've added some punctuation that helps separate the ideas and flow, but perhaps it's overall better to split it into multiple sentences or perhaps just use bullet points to express its structure.

[felix91gr]

I wonder if a link to what we mean by "subset the language" would help.

You and I know exactly what we mean by that, and people who have worked with MISRA probably understand the concept as well. But I wonder if other folks who work on Safety Critical know about it too?

Maybe there's a reference we can point to, that explains the concept?