Comments (14)
As long as the spec is clear, I think it doesn't matter a lot. If we are gonna do this, I think we should eliminate all pronouns and only mention the contributors at the start of the document. Where to put this guideline and make it visible?
from rfcs.
@louy2 "if the spec is clear"
Sure, but people (mostly me right now) have to write the spec, and it's made far more difficult when RFCs are merged with incomplete and informal language.
from rfcs.
Three examples of (first-draft) RFCs:
https://github.com/rust-lang/rfcs/blob/174e37c1e210acb8954f7357ce46529bc7f581c8/text/0000-uisize.md
(note: I'm not saying any of these are bad, just pointing out the difference in how they're layed out)
It's unclear what an RFC should be. Should it be something everyone can understand? Should it be implementation details? Should it be written in a mathematical proving language?
from rfcs.
An informal writing style seems reasonable during the feedback and
development stage of the RFC, though I agree the language should be
tightened up and formalised before being accepted+merged.
On 1 May 2014 10:12, Chris Morgan [email protected] wrote:
Take for example this snippet from
https://github.com/rust-lang/rfcs/blob/7443c30a25b7ddc10a36ee3c3344596cb60ed549/active/0003-opt-in-builtin-traits.md#implementation-plan
:Here is a loose implementation plan that @flaper87https://github.com/flaper87and I worked out.
Who is the first person here? Sure, I can look it up, but for these RFCs
an informal writing style is undesirable.Can we please mandate a formal writing style, or at the very least ban
first person writing?—
Reply to this email directly or view it on GitHubhttps://github.com//issues/61
.
from rfcs.
If we credited authors on RFCs it would at least make it obvious who "I" is.
from rfcs.
Template, which is pretty much what everybody bases their submissions
anyway. What about the old RFCs though?
On Jun 28, 2016 1:50 PM, "Yufan Lou" [email protected] wrote:
As long as the spec is clear, I think it doesn't matter a lot. If we are
gonna do this, I think we should eliminate all pronouns and only mention
the contributors at the start of the document. Where to put this guideline
and make it visible?—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#61 (comment), or mute
the thread
https://github.com/notifications/unsubscribe/AApc0jT-W09OIYEpxD9Jnwn4tAg4vg55ks5qQPyNgaJpZM4B3FBS
.
from rfcs.
What about the old RFCs though?
What about IETF style deprecation? Publish formalised ones to replace old ones. Deprecated ones are updated to point to the updated ones, and vice versa.
from rfcs.
In addition, do we have something like RFC2119 yet?
from rfcs.
@louy2 no. It's kinda... do whatever feels right, right now.
from rfcs.
@ubsan One thing in common: Drawbacks sections are short. But that's a digression and is probably not really related to form.
For reference, PEP 1 is a pretty nice guideline, but I already feel that it's a bit of a burden to read before submitting my new idea.
Ultimately, what do we want the RFCs be? Right now our RFCs seem to be at an earlier point in the discussion than others, say PEP or IETF RFC. Quote PEP 1:
Vetting an idea publicly before going as far as writing a PEP is meant to save the potential author time.
Our RFC seems to be the start of "vetting an idea publicly" instead of the result of it. Or as well as.
The enforcement better not interrupt discussion on topic. Discussion is on as soon as the RFC pull request is submitted, so that leaves enforcement to after discussion. I think a formalization before the FCP is a good timing. The RFC needs to incorporate the result of previous discussion anyway, and a formalized language can hopefully make the idea clearer for a better FCP.
As a start maybe it can be required that an RFC only enters FCP after its formalization, naturally placing the work on the creator. Help from the community is welcome always.
That was such a flow... but I forgot we can also use the pull request template to enforce structure beforehand.
As a real start, add an "Authors" field to the template.
from rfcs.
I don't think that Rust is at a place where it would benefit from 2119 style MUST and such. They clarify when multiple parties are all interpreting the text carefully and need to reach the same conclusion, but for the kinds of readings we are doing, they mostly just make the text less accessible.
It seems like mildly bad form to use the first person in the text of an RFC, but not terrible (does it matter who "I" refers to?).
I haven't found RFCs to be too informal so far; incomplete or inaccessible in other ways, perhaps, but informality hasn't been an issue to me.
from rfcs.
Triage: @chris-morgan do you intend to make this an RFC? If not, please close this.
from rfcs.
I have found that such “bans” or “requirements” hardly work anyway unless there is infrastructure to support them. I think that implementing tooling for this is not a good use of our resources.
from rfcs.
@nagisa I agree; I'll just close it (mainly since I want to reduce our ridiculous amount of issues on this repo) and someone can write up a proper proposal if they disagree.
from rfcs.
Related Issues (20)
- `const if` to supress instantiation/codegen of unreachable branches HOT 28
- Make square bracket `[]` more usable. HOT 10
- Allow using `as` to cast to different types (`As<T>` trait) HOT 10
- Better wrapper structs HOT 7
- Remove all panics from standard library HOT 25
- Generate an automatic implementation of TryFrom and Into for C-style enums HOT 5
- Redesign `Arc` API HOT 5
- Float rounding with specified digits HOT 4
- Refactor shared methods of `f32` and `f64` into new `Float` trait HOT 3
- Enable `Self = F` in generic `where` clause HOT 1
- Named opt-in trait impls HOT 2
- Question/proposal: Struct specialization HOT 3
- https://rust-lang.github.io/rfcs/0344-conventions-galore.html#lints uses `-` HOT 1
- new type of enum HOT 8
- Pre-RFC: Add a built-in support for totality (or non-panicking/aborting) asserting HOT 6
- Potential Compiler Optimization Issue with &Vec<Vec<T>> vs &[Vec<T>]? HOT 1
- Discussion/Pre-RFC/ACP: Unify privately constructed ("protected") ZSTs in std
- Create a struct similar to std::fs::File for directories HOT 2
- Converging let else HOT 1
- Conditional visibility: for integration testing purpose. HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from rfcs.