Skip to content

Commit 39cbbda

Browse files
PLeVasseurfelix91grplaindocs
authored
Add GOALS.md, revise contribution process, freshen up to use arewesafetycriticalyet.org (#149)
* Move goals into GOALS.md * Add GOALS.md link to README.md. Update URL of deployed version to arewesafetycriticalyet.org * Update GOALS.md Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Update GOALS.md Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Update GOALS.md Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Update GOALS.md Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Update GOALS.md Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Make steps more concrete on how to contribute. * Add diagram * Update contribution workflow diagram * Phrasing Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Add table of contents Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Phrasing Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Phrasing Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Phrasing Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Clarification around finding or creating lints for Clippy Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * chore: extract contribution details into CONTRIBUTION.md * feat: address what we provide for machine-readable artifacts * feat: clarify elevator pitch * feat: add link to what we mean by decidability * Making steps easier to read Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Updating headings Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Update heading, a bit of reorganization Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Clarification Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Aid in human parsing Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * fix: remove left over suggestion tag at top * docs: clarify which portion of MISRA Compliance: 2020 contains MRAD categories * docs: clarify which standards starting with and why * docs: clarify what we're providing in a machine readable format and for what purpose * docs: clarify what language subsetting means and where to find more about it * Update GOALS.md Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Fix contributing link Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> * Clarification Co-authored-by: Sam <samuel@plaindocs.com> * Clean up verbiage Co-authored-by: Sam <samuel@plaindocs.com> * Make it read better Co-authored-by: Sam <samuel@plaindocs.com> * Wording improvement Co-authored-by: Sam <samuel@plaindocs.com> * Wording improvements Co-authored-by: Sam <samuel@plaindocs.com> --------- Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com> Co-authored-by: Sam <samuel@plaindocs.com>
1 parent cc77b6a commit 39cbbda

3 files changed

Lines changed: 194 additions & 30 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 118 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,122 @@
1-
# Contributing to a Rust Foundation Project
1+
# Contributing to the coding guidelines
22

3-
Thank you for your interest in contributing to this Rust Foundation project.
4-
We are happy and excited to review and accept your pull requests.
3+
## Table of Contents
4+
5+
- [Contributing to the coding guidelines](#contributing-to-the-coding-guidelines)
6+
- [Table of Contents](#table-of-contents)
7+
- [Contribution Workflow](#contribution-workflow)
8+
- [Note on Chapter Layout](#note-on-chapter-layout)
9+
- [0) Bring up the idea for discussion](#0-bring-up-the-idea-for-discussion)
10+
- [1) Submit coding guideline issue](#1-submit-coding-guideline-issue)
11+
- [1.1) Finding the FLS ID](#11-finding-the-fls-id)
12+
- [2) Create a Draft with a Member](#2-create-a-draft-with-a-member)
13+
- [3) A Pull Request is generated](#3-a-pull-request-is-generated)
14+
- [4) Iterate on Feedback](#4-iterate-on-feedback)
15+
- [4.1) Apply changes to the Guideline's Issue](#41-apply-changes-to-the-guidelines-issue)
16+
- [4.2) Re-generate the Pull Request](#42-re-generate-the-pull-request)
17+
- [5) Your Guideline gets merged](#5-your-guideline-gets-merged)
18+
- [You just contributed a coding guideline!](#you-just-contributed-a-coding-guideline)
19+
- [Writing a guideline locally (less typical, not recommended)](#writing-a-guideline-locally-less-typical-not-recommended)
20+
- [Guideline template](#guideline-template)
21+
- [Before You Begin Contributing](#before-you-begin-contributing)
22+
- [Licenses](#licenses)
23+
- [Code of Conduct](#code-of-conduct)
24+
- [Contribution Process](#contribution-process)
25+
- [Issues](#issues)
26+
27+
## Contribution Workflow
28+
29+
Here's a diagram of the overall process:
30+
31+
```mermaid
32+
flowchart TD
33+
Start(["Start"]) --> Idea["Coding Guideline Idea"]
34+
Idea --> Zulip[/"(Optional)<br>0: Contributor brings <br> to discuss on Zulip"/]
35+
Zulip --> CreateIssue{{"1: Contributor creates <br> issue"}}
36+
CreateIssue --> Issue["Coding Guideline Issue"]
37+
38+
%% short local loops (no long edges)
39+
S2{{"2: Review started <br> by subcommittee <br> member in <= 14 days <br><br> Contributor updates accordingly"}} --> Issue
40+
Issue --> S2
41+
42+
Issue --> S3{{"3: Subcommitte member <br> assigns label<br>to generate PR"}} --> PR["Coding Guideline<br>Pull Request"]
43+
44+
S4{{"4: PR review started <br> by subcommittee member <br> in <= 14 days <br><br> Contributor discusses on PR"}} --> PR
45+
PR --> S4
46+
47+
PR --> S5{{"5: Contributor applies <br> feedback to issue"}} --> Issue
48+
Issue --> S6{{"6: Subcommittee member <br> confirms changes;<br> regenerates PR"}} --> PR
49+
PR --> S7{{"7: Subcommittee member <br> approves & queues;<br>merges to main"}} --> Main[[main]]
50+
Main --> End(["8: End"])
51+
```
52+
53+
### Note on Chapter Layout
54+
55+
The Safety Critical Rust Coding guidelines has the same chapter layout as the [Ferrocene Language Specification](https://spec.ferrocene.dev/) (FLS). If you would like to contribute a new guideline, find a section from the FLS that interests you, then write a guideline in the corresponding chapter of these coding guidelines.
56+
57+
### 0) (Optional) Bring the idea up for discussion
58+
59+
Have an idea for a coding guideline? Want to discuss it?
60+
61+
If you want to discuss the feasibility of a guideline or discuss it with others to ensure it's not too similar an existing guideline, drop by the [Safety-Critical Rust Consortium's Zulip stream](https://rust-lang.zulipchat.com/#narrow/channel/445688-safety-critical-consortium) and open a new topic.
62+
63+
### 1) Submit coding guideline issue
64+
65+
To add a new coding guideline, open a [coding guideline issue](https://github.com/rustfoundation/safety-critical-rust-coding-guidelines/issues/new?template=CODING-GUIDELINE.yml).
66+
67+
#### 1.1) Finding the FLS ID
68+
69+
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:
70+
71+
72+
```html
73+
<p><span class="spec-paragraph-id" id="fls_4rhjpdu4zfqj">4.1:1</span>
74+
```
75+
76+
You would then pull `fls_4rhjpdu4zfqj` to place in the FLS ID field.
77+
78+
### 2) Create a Draft with a Member
79+
80+
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.
81+
82+
### 3) A Pull Request is generated
83+
84+
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 automatically created.
85+
86+
### 4) Iterate on Feedback
87+
88+
The generated Pull Request may attract additional feedback or simply be an easier place to suggest targeted edits.
89+
90+
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.
91+
92+
#### 4.1) Apply changes to the Guideline's Issue
93+
94+
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.
95+
96+
#### 4.2) Re-generate the Pull Request
97+
98+
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.
99+
100+
### 5) Your Guideline gets merged
101+
102+
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.
103+
104+
### You just contributed a coding guideline!
105+
106+
That's it!
107+
108+
109+
## Writing a guideline locally (less typical, not recommended)
110+
111+
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.
112+
113+
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.
114+
115+
### Guideline template
116+
117+
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.
118+
119+
You can the copy and paste this guideline from the command line into the correct chapter.
5120

6121
## Before You Begin Contributing
7122

‎GOALS.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Goals
2+
3+
## Elevator pitch
4+
5+
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.
6+
7+
## Detailed
8+
9+
These coding guidelines will be a set of rules in the form of `do` / `do not do`, with examples covering 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.
10+
11+
There will be an addendum which covers how various safety standards like ISO 26262 map onto the coding guidelines.
12+
13+
## Criteria
14+
15+
* 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
16+
* 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.
17+
* We include a rationale with links to parts of the Rust Project and wider Rust community for guidance
18+
* We will include linkage where appropriate to to various standards, e.g. CERT C, MISRA C, DO 178, ISO 26262
19+
* We will include practical recommendations on how to use this piece of the language using compliant and non-compliant examples
20+
* We will develop an addendum matrix to 1. clarify which safety standards are supported 2. lower burden of users
21+
* We will begin with DO 178 and ISO 26262
22+
* We will begin at either the **chapter** level or the **subsection** level for now, and may expand the granularity of the matrix's mapping later
23+
* We will release the coding guidelines tagged with the versions of stable Rust that they support (e.g. `1.42`)
24+
* We will find or create Clippy lints which will cover decidable guidelines
25+
26+
### Criteria obtained by discussion with Tooling Subcommittee
27+
28+
* 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)))
29+
* 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.
30+
* We will consider only the language reference / spec, not the tooling availability when writing the coding guidelines
31+
* We aim to produce evidence-based guidelines, with statistics around human error when programming Rust, to support:
32+
1. What guidelines are written, and
33+
2. Why a specific suggestion was made
34+
* 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:
35+
* a `needs.json` containing the contents of the coding guidelines
36+
* 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
37+
38+
# Explicit non-goals
39+
40+
* For the initial version to have complete coverage of the Rust programming language
41+
* "Something" shipped to alleviate pressure at organizations is better than "nothing is available"
42+
* An accepted means of delivering partially complete coding guidelines by IEC 61508 and other
43+
similar safety standards is to subset the language.
44+
* Language subsetting as defined in IEC 61508 and ISO 26262 may be used to prevent the usage
45+
of certain language constructs which are not suitable for use in safety-critical systems.
46+
* The same mechanism can be used to subset out portions of the Rust programming language for
47+
which we do not yet have a sufficient degree of coverage via the coding guidelines.
48+
* For a more detailed treatment, please see IEC 61508:2010-7, Annex C: "C.2.6.2 Coding standards"
49+
for a breakdown in a table and "C.4.2 Language subsets" for rationale.
50+
* 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.
51+
* For any version to be conflict-free with various members' or their organizations' viewpoints
52+
* 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**.
53+
* We'd like to ship something that we can obtain broad consensus on.
54+
* 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‎

Lines changed: 22 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,24 @@
22

33
Coding Guidelines for Safety Critical Rust developed by the [Safety Critical Rust Consortium][safety-critical-rust-consortium].
44

5-
[View the latest rendered guidelines online](https://rustfoundation.github.io/safety-critical-rust-coding-guidelines/)
5+
[View the latest rendered guidelines online](https://coding-guidelines.arewesafetycriticalyet.org/)
6+
7+
Check out the [coding guideline goals](GOALS.md).
68

79
_Note_: Early, subject to changes.
810

11+
## Table of Contents
12+
- [Building the coding guidelines](#building-the-coding-guidelines)
13+
- [Running builds offline](#running-builds-offline)
14+
- [Build breaking due to out-dated spec lock file](#build-breaking-due-to-out-dated-spec-lock-file)
15+
- [Continuing work while on a feature branch](#continuing-work-while-on-a-feature-branch)
16+
- [If you need to audit the difference](#if-you-need-to-audit-the-difference)
17+
- [Outline \& issue breakdown](#outline--issue-breakdown)
18+
- [Contributing](#contributing)
19+
- [Code of Conduct](#code-of-conduct)
20+
- [Licenses](#licenses)
21+
- [Other Policies](#other-policies)
22+
923
## Building the coding guidelines
1024

1125
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
4256
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.
4357

4458

45-
## Running builds offline
59+
### Running builds offline
4660

4761
If you're working without internet access or want to avoid reaching out to remote resources, you can pass the `--offline` flag:
4862

@@ -55,7 +69,7 @@ This prevents the build system from attempting to fetch remote resources, such a
5569
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.
5670

5771

58-
## Build breaking due to out-dated spec lock file
72+
### Build breaking due to out-dated spec lock file
5973

6074
It's a fairly common occurrence for the build to break due to an out of date spec lock file, located at:
6175

@@ -101,34 +115,15 @@ Once you have completed the above steps, you will now update the local copy of t
101115

102116
Open a new PR with only the changes necessary to rationalize the guidelines with the new FLS text.
103117

104-
## Contributing to the coding guidelines
105-
106-
See [CONTRIBUTING.md](CONTRIBUTING.md).
107-
108-
### Chapter layout mirrors Ferrocene Language Specification
109-
110-
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.
111-
112-
### Guideline template
118+
## Outline & issue breakdown
113119

114-
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.
115-
116-
You can the copy and paste this guideline from the command line into the correct chapter.
117-
118-
### Filling out the guideline
119-
120-
Reference `src/conf.py` to see valid selections for unfilled options in the guideline template.
121-
122-
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:
123-
124-
```html
125-
<p><span class="spec-paragraph-id" id="fls_4rhjpdu4zfqj">4.1:1</span>
126-
```
120+
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.
127121

128-
You would then pull `fls_4rhjpdu4zfqj` to place in the `:fls:` option.
122+
## Contributing
129123

130-
Existing guidelines can also serve as examples on how guidelines are filled.
124+
Thank you for your interest in contributing to the Safety-Critical Rust Coding Guidelines!
131125

126+
Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for the details on how to do so.
132127

133128
## [Code of Conduct][code-of-conduct]
134129

0 commit comments

Comments
 (0)