Skip to content

Commit a488ca0

Browse files
CentrilCentril
authored
Merge pull request #2333 from Centril/rfc/prior-art
Meta-RFC: Prior art
2 parents 417f92d + 9c8bdaa commit a488ca0

File tree

2 files changed

+216
-0
lines changed

2 files changed

+216
-0
lines changed

‎0000-template.md

+17
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,23 @@ Why should we *not* do this?
4949
- What other designs have been considered and what is the rationale for not choosing them?
5050
- What is the impact of not doing this?
5151

52+
# Prior art
53+
[prior-art]: #prior-art
54+
55+
Discuss prior art, both the good and the bad, in relation to this proposal.
56+
A few examples of what this can include are:
57+
58+
- For language, library, cargo, tools, and compiler proposals: Does this feature exists in other programming languages and what experience have their community had?
59+
- For community proposals: Is this done by some other community and what were their experiences with it?
60+
- For other teams: What lessons can we learn from what other communities have done here?
61+
- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background.
62+
63+
This section is intended to encourage you as an author to think about the lessons from other languages, provide readers of your RFC with a fuller picture.
64+
If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other languages.
65+
66+
Note that while precedent set by other languages is some motivation, it does not on its own motivate an RFC.
67+
Please also take into consideration that rust sometimes intentionally diverges from common language features.
68+
5269
# Unresolved questions
5370
[unresolved]: #unresolved-questions
5471

‎text/2333-prior-art.md

+199
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
- Feature Name: `prior_art`
2+
- Start Date: 2018-02-12
3+
- RFC PR: [rust-lang/rfcs#2333](https://github.com/rust-lang/rfcs/pull/2333)
4+
- Rust Issue: **self-executing**
5+
6+
# Summary
7+
[summary]: #summary
8+
9+
Adds a *Prior art* section to the RFC template where RFC authors
10+
may discuss the experience of other programming languages and their
11+
communities with respect to what is being proposed. This section may
12+
also discuss theoretical work such as papers.
13+
14+
# Motivation
15+
[motivation]: #motivation
16+
17+
## Precedent has some importance
18+
19+
It is arguable whether or not precedent is important or whether proposals
20+
should be considered solely on their own merits. This RFC argues that
21+
precedent is important.
22+
23+
Precedent and in particular familiarity in and from other languages may
24+
inform our choices in terms of naming, especially if that other language
25+
is similar to Rust.
26+
27+
For additions to the standard library in particular, it should carry some
28+
weight if a feature is supported in mainstream languages because the users
29+
of those languages, which may also be rustaceans, are used to those features.
30+
This is not to say that precedent alone is sufficient motivation for accepting
31+
an RFC; but neither is it useless.
32+
33+
## Experiences from other languages are useful
34+
35+
This is the chief motivation of this RFC. By explicitly asking authors for
36+
information about the similarity of their proposal to those in other languages,
37+
we may get more information which aids us in better evaluating RFCs. Merely name
38+
dropping that a language has a certain feature is not all - a discussion of the
39+
experience the communities of the language in question has had is more useful.
40+
A proposal need also not be a language or library proposal. If a proposal is
41+
made for changes to how we work as a community, it can be especially valuable
42+
how other communities have tackled a similar situation.
43+
44+
### Experiences are useful to the author themselves
45+
46+
During the process of writing an RFC, an author may change certain aspects
47+
of the proposal from what they originally had in mind. They may tweak the RFC,
48+
change certain aspects in a more radical way, and so on. Here, the benefit of
49+
explicitly asking for and about prior art is that it makes the RFC author think
50+
about the proposal in relation to other languages. In search for this
51+
information, the author can come to new or better realizations about the
52+
trade-offs, advantages, and drawbacks of their proposal. Thus, their RFC as
53+
a whole is hopefully improved as a by-product.
54+
55+
## Papers can provide greater theoretical understanding
56+
57+
This RFC argues that it valuable to us to be provided with papers or similar
58+
that explain proposals and/or their theoretical foundations in greater detail
59+
where such resources exist. This provides RFC readers with references if they
60+
want a deeper understanding of an RFC. At the same time, this alleviates the
61+
need to explain the minutiae of the theoretical background. The finer details
62+
can instead be referred to the referred-to papers.
63+
64+
## An improved historical record of Rust for posterity
65+
66+
Finally, by writing down and documenting where our ideas came from,
67+
we can better preserve the history and evolution of Rust for posterity.
68+
While this is not very important in right now, it will increase somewhat
69+
in importance as time goes by.
70+
71+
# Guide-level explanation
72+
[guide-level-explanation]: #guide-level-explanation
73+
74+
This Meta-RFC modifies the RFC template by adding a *Prior art* section
75+
before the *Unresolved questions*. The newly introduced section is intended
76+
to help authors reflect on the experience other languages have had with similar
77+
and related concepts. This is meant to improve the RFC as a whole, but also
78+
provide RFC readers with more details so that the proposal may be more fairly
79+
and fully judged. The section also asks authors for other resources such as
80+
papers where those exist. Finally, the section notes that precedent from other
81+
languages on its own is not sufficient motivation to accept an RFC.
82+
83+
Please read the [reference-level-explanation] for exact details of what an RFC
84+
author will see in the changed template.
85+
86+
# Reference-level explanation
87+
[reference-level-explanation]: #reference-level-explanation
88+
89+
The implementation of this RFC consists of inserting the following
90+
text to the RFC template before the section *Unresolved questions*:
91+
92+
> # Prior art
93+
>
94+
> Discuss prior art, both the good and the bad, in relation to this proposal.
95+
> A few examples of what this can include are:
96+
>
97+
> - For language, library, cargo, tools, and compiler proposals:
98+
> Does this feature exists in other programming languages and
99+
> what experience have their community had?
100+
> - For community proposals: Is this done by some other community and what
101+
> were their experiences with it?
102+
> - For other teams: What lessons can we learn from what other communities
103+
> have done here?
104+
> - Papers: Are there any published papers or great posts that discuss this?
105+
> If you have some relevant papers to refer to, this can serve as a more
106+
> detailed theoretical background.
107+
>
108+
> This section is intended to encourage you as an author to think about
109+
> the lessons from other languages, provide readers of your RFC with a
110+
> fuller picture. If there is no prior art, that is fine - your ideas are
111+
> interesting to us whether they are brand new or if it is an adaptation
112+
> from other languages.
113+
>
114+
> Note that while precedent set by other languages is some motivation, it does
115+
> not on its own motivate an RFC. Please also take into consideration that rust
116+
> sometimes intentionally diverges from common language features.
117+
118+
# Drawbacks
119+
[drawbacks]: #drawbacks
120+
121+
This might encourage RFC authors into the thinking that just because a feature
122+
exists in one language, it should also exist in Rust and that this can be the
123+
sole argument. This RFC argues that the risk of this is small, and that with a
124+
clear textual instruction in the RFC template, we can reduce it even further.
125+
126+
Another potential drawback is the risk that in a majority of cases, the prior
127+
art section will simply be left empty with "N/A". Even if this is the case,
128+
there will still be an improvement to the minority of RFCs that do include a
129+
review of prior art. Furthermore, this the changes to the template proposed
130+
in this RFC are by no means irreversible. If we find out after some time that
131+
this was a bad idea, we can always revert back to the way it was before.
132+
133+
Finally, a longer template risks making it harder to contribute to the
134+
RFC process as an author as you are expected to fill in more sections.
135+
Some people who don't know a lot of other langauges may be intimidated into
136+
thinking that they are expected to know a wide variety of langauges and that
137+
their contribution is not welcome otherwise. This drawback can be mitigated
138+
by more clearly communicating that the RFC process is a collaborative effort.
139+
If an author does not have prior art to offer up right away, other participants
140+
in the RFC discussion may be able to provide such information which can then
141+
be amended into the RFC.
142+
143+
# Rationale and alternatives
144+
[alternatives]: #alternatives
145+
146+
If we don't change the template as proposed in this RFC, the downsides
147+
are that we don't get the benefits enumerated within the [motivation].
148+
149+
As always, there is the simple alternative of not doing the changes proposed
150+
in the RFC.
151+
152+
Other than that, we can come to the understanding that those that
153+
want may include a prior art section if they wish, even if it is not
154+
in the template. This is already the case - authors can always provide
155+
extra information. The benefit of asking for the information explicitly
156+
in the template is that more authors are likely to provide such information.
157+
This is discussed more in the [motivation].
158+
159+
Finally, we can ask for information about prior art to be provided in each
160+
section (motivation, guide-level explanation, etc.). This is however likely to
161+
reduce the coherence and readability of RFCs. This RFC argues that it is better
162+
that prior art be discussed in one coherent section. This is also similar to
163+
how papers are structured in that they include a "related work" section.
164+
165+
# Prior art
166+
[prior-art]: #prior-art
167+
168+
In many papers, a section entitled *Related work* is included which can
169+
be likened to this section. To not drive readers away or be attention
170+
stealing from the main contributions of a paper, it is usually recommended
171+
that this section be placed near the end of papers. For the reasons mentioned,
172+
this is a good idea - and so to achieve the same effect, the section you are
173+
currently reading will be placed precisely where it is placed right now, that
174+
is, before the *Unresolved questions* section, which we can liken to a
175+
*Future work* section inside a paper.
176+
177+
A review of the proposal templates for [`C++`], [`python`], [`Java`], [`C#`],
178+
[`Scala`], [`Haskell`], [`Swift`], and [`Go`] did not turn up such a section
179+
within those communities templates. Some of these templates are quite similar
180+
and have probably inspired each other. To the RFC authors knowledge, no other
181+
mainstream programming language features a section such as this.
182+
183+
[`C++`]: https://isocpp.org/std/submit-a-proposal
184+
[`python`]: https://github.com/python/peps/blob/master/pep-0001.txt
185+
[`Java`]: http://openjdk.java.net/jeps/2
186+
[`C#`]: https://github.com/dotnet/csharplang/blob/master/proposals/proposal-template.md
187+
[`Haskell`]: https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0000-template.rst
188+
[`Scala`]: https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md
189+
[`Go`]: https://github.com/golang/proposal/blob/master/design/TEMPLATE.md
190+
[`Swift`]: https://github.com/apple/swift-evolution/blob/master/0000-template.md
191+
192+
# Unresolved questions
193+
[unresolved]: #unresolved-questions
194+
195+
There are none as of yet.
196+
197+
What is important in this RFC is that we establish whether we want a
198+
prior art section or not, and what it should contain in broad terms.
199+
The exact language and wording can always be tweaked beyond this.

0 commit comments

Comments
 (0)