Add GOALS.md, freshen up to use arewesafetycriticalyet.org #149
Conversation
❌ Deploy Preview for scrc-coding-guidelines failed.
|
…wesafetycriticalyet.org
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 |
|
|
||
| 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 👍
|
|
||
| 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
|
|
||
| ## 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 :)
| * Include for each a minimum of one compliant and non-compliant example of code to illustrate point | ||
| * Consider only the language reference / spec, not the tooling availability when writing the coding guidelines | ||
| * Evidence-based with statistics around human error when programming Rust to support both 1. what guidelines are written and 2. why a suggestion was made | ||
| * 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.
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)
Oh wow, that's a big requirement. Did they offer examples on this? I don't think there's any representation generic enough to describe an arbitrary guideline in a machine-readable format.
Aside: if it exists, let me know. Such a representation could be used to automatically construct lints.
Therefore, I must be misinterpreting this requirement.
Do you think we could ask around in the Tooling Subcommittee Zulip thread?
There was a problem hiding this comment.
Yeah, this is a good question.
My current understanding after bringing this to the Tooling Subcommittee was that the following would suffice:
needs.jsonwhich bundles together all of theguidelines directives we have so could be consumed by a toolguidelines-ids.jsonwhich stamps eachguidelinedirective with a hash of the contents so that a tool vendor could be aware of when a guideline has changed and thus intentionally break their build
But yeah we can definitely shop it around again to make sure this fits their needs.
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]>
Closes #145