Skip to content

Commit 07eb29f

Browse files
mark-i-mmark-i-m
committedNov 11, 2018
start on walkthrough
1 parent ade4a4e commit 07eb29f

File tree

1 file changed

+147
-0
lines changed

1 file changed

+147
-0
lines changed
 

‎src/walkthrough.md

+147
Original file line numberDiff line numberDiff line change
@@ -1 +1,148 @@
11
# Walkthrough: a typical contribution
2+
3+
There are _a lot_ of ways to contribute to the rust compiler, including fixing
4+
bugs, improving performance, helping design features, providing feedback on
5+
existing features, etc. This chapter does not claim to scratch the surface.
6+
Instead, it walks through the design and implementation of a new feature. Not
7+
all of the steps and processes described here are needed for every
8+
contribution, and I will try to point those out as they arise.
9+
10+
In general, if you are interested in making a contribution and aren't sure
11+
where to start, please feel free to ask!
12+
13+
## Overview
14+
15+
The feature I will discuss in this chapter is the `?` Kleene operator for
16+
macros. Basically, we want to be able to write something like this:
17+
18+
```rust
19+
macro_rules! foo {
20+
($arg:ident $(, $optional_arg:ident)?) => {
21+
println!("{}", $arg);
22+
23+
$(
24+
println!("{}", $optional_arg);
25+
)?
26+
}
27+
}
28+
29+
fn main() {
30+
let x = 0;
31+
foo!(x); // ok! prints "0"
32+
foo!(x, x); // ok! prints "0 0"
33+
}
34+
```
35+
36+
So basically, the `$(pat)?` matcher in the macro means "this pattern can occur
37+
0 or 1 times", similar to other regex syntaxes.
38+
39+
There were a number of steps to go from an idea to stable rust feature. Here is
40+
a quick list. We will go through each of these in order below. As I mentioned
41+
before, not all of these are needed for every type of contribution.
42+
43+
- **Idea discussion/Pre-RFC** A Pre-RFC is an early draft or design discussion
44+
of a feature. This stage is intended to flesh out the design space a bit and
45+
get a grasp on the different merits and problems with an idea. It's a great
46+
way to get early feedback on your idea before presenting it the wider
47+
audience. You can find the original discussion [here][prerfc].
48+
- **RFC** This is when you formally present your idea to the community for
49+
consideration. You can find the RFC [here][rfc].
50+
- **Implementation** Implement your idea unstabley in the compiler. You can
51+
find the original implementation [here][impl1].
52+
- **Possibly iterate/refine** As the community gets experience with your
53+
feature on the nightly compiler and in `libstd`, there may be additional
54+
feedback about design choice that might be adjusted. This particular feature
55+
went [through][impl2] a [number][impl3] of [iterations][impl4].
56+
- **Stabilization** When your feature has baked enough, a rust team member may
57+
[propose to stabilize it][merge]. If there is consensus, this is done.
58+
- **Relax** Your feature is now a stable rust feature!
59+
60+
[prerfc]: https://internals.rust-lang.org/t/pre-rfc-at-most-one-repetition-macro-patterns/6557
61+
[rfc]: https://github.com/rust-lang/rfcs/pull/2298
62+
[impl1]: https://github.com/rust-lang/rust/pull/47752
63+
[impl2]: https://github.com/rust-lang/rust/pull/49719
64+
[impl3]: https://github.com/rust-lang/rust/pull/51336
65+
[impl4]: https://github.com/rust-lang/rust/pull/51587
66+
[merge]: https://github.com/rust-lang/rust/issues/48075#issuecomment-433177613
67+
68+
## Pre-RFC and RFC
69+
70+
> NOTE: In general, if you are not proposing a _new_ feature or substantial
71+
> change to rust or the ecosystem, you don't need to follow the RFC process.
72+
> Instead, you can just jump to [implementation](#impl).
73+
>
74+
> You can find the official guidelines for when to open an RFC [here][rfcwhen].
75+
76+
[rfcwhen]: https://github.com/rust-lang/rfcs#when-you-need-to-follow-this-process
77+
78+
An RFC is a document that describes the feature or change you are proposing in
79+
detail. Anyone can write an RFC; the process is the same for everyone,
80+
including rust team members.
81+
82+
To open an RFC, open a PR on the
83+
[rust-lang/rfcs](https://github.com/rust-lang/rfcs) repo on GitHub. You can
84+
find detailed instructions in the
85+
[README](https://github.com/rust-lang/rfcs#what-the-process-is).
86+
87+
Before opening an RFC, you should do the research to "flesh out" your idea.
88+
Hastily-proposed RFCs tend not to be accepted. You should generally have a good
89+
description of the motivation, impact, disadvantages, and potential
90+
interactions with other features.
91+
92+
If that sounds like a lot of work, it's because it is. But no fear! Even if
93+
you're not a compiler hacker, you can get great feedback by doing a _pre-RFC_.
94+
This is an _informal_ discussion of the idea. The best place to do this is
95+
internals.rust-lang.org. Your post doesn't have to follow any particular
96+
structure. It doesn't even need to be a cohesive idea. Generally, you will get
97+
tons of feedback that you can integrate back to produce a good RFC.
98+
99+
(Another pro-tip: try searching the RFCs repo and internals for prior related
100+
ideas. A lot of times an idea has already been considered and was either
101+
rejected or postponed to be tried again later. This can save you and everybody
102+
else some time)
103+
104+
In the case of our example, a participant in the pre-RFC thread pointed out a
105+
syntax ambiguity and a potential resolution. Also, the overall feedback seemed
106+
positive. In this case, the discussion converged pretty quickly, but for some
107+
ideas, a lot more discussion can happen (e.g. see [this RFC][nonascii] which
108+
received a whopping 684 comments!). If that happens, don't be discouraged; it
109+
means the community is interested in your idea, but it perhaps needs some
110+
adjustments.
111+
112+
[nonascii]: https://github.com/rust-lang/rfcs/pull/2457
113+
114+
The RFC for our `?` macro feature did receive some discussion on the RFC thread
115+
too. As with most RFCs, there were a few questions that we couldn't answer by
116+
discussion: we needed experience using the feature to decide. Such questions
117+
are listed in the "Unresolved Questions" section of the RFC. Also, over the
118+
course of the RFC discussion, you will probably want to update the RFC document
119+
itself to reflect the course of the discussion (e.g. new alternatives or prior
120+
work may be added or you may decide to change parts of the proposal itself).
121+
122+
In the end, when the discussion seems to reach a consensus and die down a bit,
123+
a rust team member may propose [to merge the RFC][rfcmerge]. This means that
124+
they want the other members of the appropriate teams to review and comment on
125+
the RFC. More changes may be proposed. At some point, when everyone is
126+
satisfied, the RFC enters the "final comment period" (FCP), which is the last
127+
chance for people to bring up objections. When the FCP is over, the RFC is
128+
"merged" (or accepted).
129+
130+
[rfcmerge]: https://github.com/rust-lang/rfcs/pull/2298#issuecomment-360582667
131+
132+
Some other possible outcomes might be for a team member to propose to
133+
134+
- _Close_: this feature in its current form is not a good fit for rust. Don't
135+
be discouraged if this happens to your RFC, and don't take it personally.
136+
This is not a reflection on you, but rather a community decision that rust
137+
will go a different direction.
138+
- _Postpone_: there is interest in going this direction but not at the moment.
139+
This happens most often because the appropriate rust team doesn't have the
140+
bandwidth to shepherd the feature through the process to stabilization. Often
141+
this is the case when the feature doesn't fit into the team's roadmap.
142+
Postponed ideas may be revisited later.
143+
144+
<a name="impl"></a>
145+
146+
## Implementation
147+
148+
TODO

0 commit comments

Comments
 (0)
Please sign in to comment.