Add GOALS.md, revise contribution process, freshen up to use arewesafetycriticalyet.org #149
Conversation
✅ Deploy Preview for scrc-coding-guidelines ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
PLeVasseur
force-pushed
the
feature/coding-guidelines-goals
branch
from
99c4170 to
863169b
Compare
|
@PLeVasseur do you want me to take a look at this? :) |
|
That'd be very kind of you ;D |
README.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
I don't know how I'd change this phrasing, but here's my observation: we now have an automatic PR builder after a Coding Guideline issue has been approved, right? Perhaps this description of the process could be changed, then, since it's now a different process than what is described in this line. Does that make sense?
There was a problem hiding this comment.
Agreed, this should be updated to reflect current reality 👍
GOALS.md
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
Most of the items in # Goals lack a verb to anchor them to the world. I think those are really important for goal-setting
- To have coding guidelines that make a "best effort" attempt (...)
- To have practical recommendations on how to (...)
- (this one is ok)
- (same)
- To have (find or create) Clippy lints which will cover decidable guidelines.
There was a problem hiding this comment.
This is a very salient point
I'll visit this again
There was a problem hiding this comment.
I tried my hand at this; could you look again?
There was a problem hiding this comment.
OH! Awesome! Yes, I shall :)
There was a problem hiding this comment.
It's now under Criteria, right?
GOALS.md
Outdated
|
|
||
| ## Goals obtained by discussion with Tooling Subcommittee | ||
|
|
||
| * Make a label for each which _in theory_ is decidable or not |
There was a problem hiding this comment.
For each... guideline, right?
(I'd make it explicit: Make a label for each guideline)
Though if we're talking about guidelines, I'd perhaps phrase it a bit differently, because the sentence feels a bit weird right now:
Make a label for each guideline, which describes whether said guideline is decidable or not.
Plus a link to our definition of decidable, or the Wikipedia article on Decidability otherwise.
Decidability is always a theoretical thing. So I think it's fine to omit the in theory bit. As long as we give the reader a link to know the fine details of it, I think that's plenty good enough :)
There was a problem hiding this comment.
I've revised the wording on this -- could you take a look?
There was a problem hiding this comment.
I think it's a lot better now! I would still add a link to a definition of decidability tho, just so that people who need a refresher or haven't studied CS and read the text know where to go for more details :)
…wesafetycriticalyet.org
Co-authored-by: Félix Fischer <[email protected]>
Co-authored-by: Félix Fischer <[email protected]>
Co-authored-by: Félix Fischer <[email protected]>
Co-authored-by: Félix Fischer <[email protected]>
Co-authored-by: Félix Fischer <[email protected]>
PLeVasseur
force-pushed
the
feature/coding-guidelines-goals
branch
from
59cb10c to
4f0f9fe
Compare
PLeVasseur
force-pushed
the
feature/coding-guidelines-goals
branch
from
7f7e285 to
7c89bd9
Compare
PLeVasseur
force-pushed
the
feature/coding-guidelines-goals
branch
2 times, most recently
from
46d94f8 to
494cbda
Compare
PLeVasseur
force-pushed
the
feature/coding-guidelines-goals
branch
from
494cbda to
ff367d1
Compare
PLeVasseur
changed the title
| Check out the [coding guideline goals](GOALS.md). | ||
|
|
||
| _Note_: Early, subject to changes. | ||
|
|
There was a problem hiding this comment.
| ## 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) | |
| - [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) | |
| - [Code of Conduct](#code-of-conduct) | |
| - [Licenses](#licenses) | |
| - [Other Policies](#other-policies) | |
Now that the README has this size, perhaps it makes sense to have a Table of Contents. I auto-generated this one using a VSCode extension; in case you'd like to be able to make one like this and be able to correct it if something changes ^^: https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one :)
|
|
||
| ## Elevator pitch | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Something about this sentence is missing, I believe.
Was it intended to go like:
We will make sure Rust coding guidelines are available within this repository, (...)
or perhaps something along the lines of...
We will make Rust coding guidelines. Such guidelines are available within this repository, (...)
|
|
||
| ## 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 reasonable coverage of the language. |
There was a problem hiding this comment.
| 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. | |
| 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. |
| * 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 as a baseline (e.g. multiple JSON files, one per language piece, also potentially one large JSON concatenated together) |
There was a problem hiding this comment.
What do you mean here by "as a baseline"? :o
|
|
||
| # Explicit non-goals | ||
|
|
||
| * For the initial version to be complete coverage of the Rust programming language |
There was a problem hiding this comment.
| * For the initial version to be complete coverage of the Rust programming language | |
| * For the initial version to have complete coverage of the Rust programming language |
| * 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 Rust programming language constructs should be viewed and approached. This is **okay and expected**. |
There was a problem hiding this comment.
| * Members and their organizations may take different stances on how Rust programming language constructs should be viewed and approached. This is **okay and expected**. | |
| * 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**. |
I believe this is better phrased this way. The capitalization is orthogonal to that, but I believe that is correct as well? Since the phrase The Rust Programming Language is being used as a name here.
Though maybe you meant it to be something like this?
Rust's programming language constructs
Though then I feel like the programming language bit could be elided, so that's probably not it:
Rust's constructs
| * For any version to be conflict-free with various members' or their organizations' viewpoints | ||
| * 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. |
There was a problem hiding this comment.
| * Worst case scenario: there may be a section here or there which you may need to adjust in an internal version that'd downstream. | |
| * 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. |
I changed it from "you" to "a user" to up the formality a bit (I'm not sure how important that is, but since it's the GOALS document, perhaps that's the voice in which we want to write it?)
I adjusted the rest because otherwise the order of operations wasn't as clear. Is this how you intended it, @PLeVasseur? Or did I misinterpret the scenario? x3
| ## 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 |
There was a problem hiding this comment.
Which part of the MISRA Compliance: 2020 document are we using? (the pdf is 39 pages long)
| ## Contributing to the coding guidelines | ||
|
|
||
| See [CONTRIBUTING.md](CONTRIBUTING.md). |
There was a problem hiding this comment.
I wonder if this entire section should go inside of CONTRIBUTING.md instead?
| * 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 |
There was a problem hiding this comment.
| * We will create Clippy lints which will cover decidable guidelines | |
| * We will find or create Clippy lints which will cover decidable guidelines |
I add this because we're thinking of using existing lints and not just create new ones :)
Closes #145