From 802edabdacfcb26426f9b7f543346ff8d1baba1d Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Tue, 13 Feb 2018 00:03:12 +0100 Subject: [PATCH 1/7] rfc, prior-art: initial version --- text/0000-prior-art.md | 188 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 text/0000-prior-art.md diff --git a/text/0000-prior-art.md b/text/0000-prior-art.md new file mode 100644 index 000000000..71b01ae7a --- /dev/null +++ b/text/0000-prior-art.md @@ -0,0 +1,188 @@ +- Feature Name: in_other_programming_languages +- Start Date: 2018-02-12 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +Adds a *Prior art* section to the RFC template where RFC authors +may discuss the experience of other programming languages and their +communities with respect to what is being proposed. This section may +also discuss theoretical work such as papers. + +# Motivation +[motivation]: #motivation + +## Precedent has some importance + +It is arguable whether or not precedent is important or whether proposals +should be considered solely on their own merits. This RFC argues that +precedent is important. + +Precedent and in particular familiarity in and from other languages may +inform our choices in terms of naming, especially if that other language +is similar to Rust. + +For additions to the standard library in particular, it should carry some +weight if a feature is supported in mainstream languages because the users +of those languages, which may also be rustaceans, are used to those features. +This is not to say that precedent alone is sufficient motivation for accepting +an RFC; but neither is it useless. + +## Experiences from other languages are useful + +This is the chief motivation of this RFC. By explicitly asking authors for +information about the similarity of their proposal to those in other languages, +we may get more information which aids us in better evaluating RFCs. Merely name +dropping that a language has a certain feature is not all - a discussion of the +experience the communities of the language in question has had is more useful. +A proposal need also not be a language or library proposal. If a proposal is +made for changes to how we work as a community, it can be especially valuable +how other communities have tackled a similar situation. + +### Experiences are useful to the author themselves + +During the process of writing an RFC, an author may change certain aspects +of the proposal from what they originally had in mind. They may tweak the RFC, +change certain aspects in a more radical way, and so on. Here, the benefit of +explicitly asking for and about prior art is that it makes the RFC author think +about the proposal in relation to other languages. In search for this +information, the author can come to new or better realizations about the +trade-offs, advantages, and drawbacks of their proposal. Thus, their RFC as +a whole is hopefully improved as a by-product. + +## Papers can provide greater theoretical understanding + +This RFC argues that it valuable to us to be provided with papers or similar +that explain proposals and/or their theoretical foundations in greater detail +where such resources exist. This provides RFC readers with references if they +want a deeper understanding of an RFC. At the same time, this alleviates the +need to explain the minutiae of the theoretical background. The finer details +can instead be referred to the referred-to papers. + +## An improved historical record of Rust for posterity + +Finally, by writing down and documenting where our ideas came from, +we can better preserve the history and evolution of Rust for posterity. +While this is not very important in right now, it will increase somewhat +in importance as time goes by. + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +This Meta-RFC modifies the RFC template by adding a *Prior art* section +before the *Unresolved questions*. The newly introduced section is intended +to help authors reflect on the experience other languages have had with similar +and related concepts. This is meant to improve the RFC as a whole, but also +provide RFC readers with more details so that the proposal may be more fairly +and fully judged. The section also asks authors for other resources such as +papers where those exist. Finally, the section notes that precedent from other +languages on its own is not sufficient motivation to accept an RFC. + +Please read the [reference-level-explanation] for exact details of what an RFC +author will see in the changed template. + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +The implementation of this RFC consists of inserting the following +text to the RFC template before the section *Unresolved questions*: + +> # Prior art +> +> Discuss prior art, both the good and the bad, in relation to this proposal. +> A few examples of what this can include are: +> +> - For language, library, cargo, tools, and compiler proposals: +> Does this feature exists in other programming languages and +> what experience has their communities have had with the feature? +> - For community proposals: Is this done by some other community and what +> were their experiences with it? +> - For other teams: What lessons can we learn from what other communities +> have done here? +> - 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. +> +> 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. 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. +> +> Note that while precedent set by other languages is some motivation, +> it does not on its own motivate an RFC. + +# Drawbacks +[drawbacks]: #drawbacks + +This might encourage RFC authors into the thinking that just because a feature +exists in one language, it should also exist in Rust and that this can be the +sole argument. This RFC argues that the risk of this is small, and that with a +clear textual instruction in the RFC template, we can reduce it even further. + +Another potential drawback is the risk that in a majority of cases, the prior +art section will simply be left empty with "N/A". Even if this is the case, +there will still be an improvement to the minority of RFCs that do include a +review of prior art. Furthermore, this the changes to the template proposed +in this RFC are by no means irreversible. If we find out after some time that +this was a bad idea, we can always revert back to the way it was before. + +# Rationale and alternatives +[alternatives]: #alternatives + +If we don't change the template as proposed in this RFC, the downsides +are that we don't get the benefits enumerated within the [motivation]. + +As always, there is the simple alternative of not doing the changes proposed +in the RFC. + +Other than that, we can come to the understanding that those that +want may include a prior art section if they wish, even if it is not +in the template. This is already the case - authors can always provide +extra information. The benefit of asking for the information explicitly +in the template is that more authors are likely to provide such information. +This is discussed more in the [motivation]. + +Finally, we can ask for information about prior art to be provided in each +section (motivation, guide-level explanation, etc.). This is however likely to +reduce the coherence and readability of RFCs. This RFC argues that it is better +that prior art be discussed in one coherent section. This is also similar to +how papers are structured in that they include a "related work" section. + +# Prior art +[prior-art]: #prior-art + +In many papers, a section entitled *Related work* is included which can +be likened to this section. To not drive readers away or be attention +stealing from the main contributions of a paper, it is usually recommended +that this section be placed near the end of papers. For the reasons mentioned, +this is a good idea - and so to achieve the same effect, the section you are +currently reading will be placed precisely where it is placed right now, that +is, before the *Unresolved questions* section, which we can liken to a +*Future work* section inside a paper. + +A review of the proposal templates for [`C++`], [`python`], [`Java`], [`C#`], +[`Scala`], [`Haskell`], [`Swift`], and [`Go`] did not turn up such a section +within those communities templates. Some of these templates are quite similar +and have probably inspired each other. To the RFC authors knowledge, no other +mainstream programming language features a section such as this. + +[`C++`]: https://isocpp.org/std/submit-a-proposal +[`python`]: https://github.com/python/peps/blob/master/pep-0001.txt +[`Java`]: http://openjdk.java.net/jeps/2 +[`C#`]: https://github.com/dotnet/csharplang/blob/master/proposals/proposal-template.md +[`Haskell`]: https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0000-template.rst +[`Scala`]: https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md +[`Go`]: https://github.com/golang/proposal/blob/master/design/TEMPLATE.md +[`Swift`]: https://github.com/apple/swift-evolution/blob/master/0000-template.md + +# Unresolved questions +[unresolved]: #unresolved-questions + +There are none as of yet. + +What is important in this RFC is that we establish whether we want a +prior art section or not, and what it should contain in broad terms. +The exact language and wording can always be tweaked beyond this. \ No newline at end of file From f08f881847850d5d587e3504088a11fad766e51b Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Tue, 13 Feb 2018 00:03:30 +0100 Subject: [PATCH 2/7] rfc, prior-art: self-execute in template --- 0000-template.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/0000-template.md b/0000-template.md index c6bc452ce..444a733c0 100644 --- a/0000-template.md +++ b/0000-template.md @@ -49,6 +49,22 @@ Why should we *not* do this? - What other designs have been considered and what is the rationale for not choosing them? - What is the impact of not doing this? +# Prior art +[prior-art]: #prior-art + +Discuss prior art, both the good and the bad, in relation to this proposal. +A few examples of what this can include are: + +- For language, library, cargo, tools, and compiler proposals: Does this feature exists in other programming languages and what experience has their communities have had with the feature? +- For community proposals: Is this done by some other community and what were their experiences with it? +- For other teams: What lessons can we learn from what other communities have done here? +- 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. + +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. +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. + +Note that while precedent set by other languages is some motivation, it does not on its own motivate an RFC. + # Unresolved questions [unresolved]: #unresolved-questions From 9ca432a429c4f33de9b9c18c129d960aa9e933da Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Tue, 13 Feb 2018 00:04:06 +0100 Subject: [PATCH 3/7] rfc, prior-art: fix feature name --- text/0000-prior-art.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-prior-art.md b/text/0000-prior-art.md index 71b01ae7a..5db71dacd 100644 --- a/text/0000-prior-art.md +++ b/text/0000-prior-art.md @@ -1,4 +1,4 @@ -- Feature Name: in_other_programming_languages +- Feature Name: prior_art - Start Date: 2018-02-12 - RFC PR: (leave this empty) - Rust Issue: (leave this empty) From 1118f8872d0395e13f843cdda318bb16e7dc1642 Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Thu, 15 Feb 2018 06:18:52 +0100 Subject: [PATCH 4/7] rfc, prior-art: fix grammar, thanks @wycats --- 0000-template.md | 2 +- text/0000-prior-art.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/0000-template.md b/0000-template.md index 444a733c0..5ed20d703 100644 --- a/0000-template.md +++ b/0000-template.md @@ -55,7 +55,7 @@ Why should we *not* do this? Discuss prior art, both the good and the bad, in relation to this proposal. A few examples of what this can include are: -- For language, library, cargo, tools, and compiler proposals: Does this feature exists in other programming languages and what experience has their communities have had with the feature? +- For language, library, cargo, tools, and compiler proposals: Does this feature exists in other programming languages and what experience have their community had? - For community proposals: Is this done by some other community and what were their experiences with it? - For other teams: What lessons can we learn from what other communities have done here? - 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. diff --git a/text/0000-prior-art.md b/text/0000-prior-art.md index 5db71dacd..b7e9813f7 100644 --- a/text/0000-prior-art.md +++ b/text/0000-prior-art.md @@ -96,7 +96,7 @@ text to the RFC template before the section *Unresolved questions*: > > - For language, library, cargo, tools, and compiler proposals: > Does this feature exists in other programming languages and -> what experience has their communities have had with the feature? +> what experience have their community had? > - For community proposals: Is this done by some other community and what > were their experiences with it? > - For other teams: What lessons can we learn from what other communities From e225f1be3b701a2cceee98cc52b183195ae46640 Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Thu, 15 Feb 2018 06:28:46 +0100 Subject: [PATCH 5/7] rfc, prior-art: communicate intentional divergence per @wycats's comments --- 0000-template.md | 1 + text/0000-prior-art.md | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/0000-template.md b/0000-template.md index 5ed20d703..6eec564d6 100644 --- a/0000-template.md +++ b/0000-template.md @@ -64,6 +64,7 @@ This section is intended to encourage you as an author to think about the lesson 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. Note that while precedent set by other languages is some motivation, it does not on its own motivate an RFC. +Please also take into consideration that rust sometimes intentionally diverges from common language features. # Unresolved questions [unresolved]: #unresolved-questions diff --git a/text/0000-prior-art.md b/text/0000-prior-art.md index b7e9813f7..f26a75261 100644 --- a/text/0000-prior-art.md +++ b/text/0000-prior-art.md @@ -111,8 +111,9 @@ text to the RFC template before the section *Unresolved questions*: > interesting to us whether they are brand new or if it is an adaptation > from other languages. > -> Note that while precedent set by other languages is some motivation, -> it does not on its own motivate an RFC. +> Note that while precedent set by other languages is some motivation, it does +> not on its own motivate an RFC. Please also take into consideration that rust +> sometimes intentionally diverges from common language features. # Drawbacks [drawbacks]: #drawbacks From 7e9d70d3d61c8d2ab9f72e7d74d02c1915446e8b Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Thu, 15 Feb 2018 06:38:47 +0100 Subject: [PATCH 6/7] rfc, prior-art: add drawback of longer template per @est31's comments --- text/0000-prior-art.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/text/0000-prior-art.md b/text/0000-prior-art.md index f26a75261..22fa3ddd7 100644 --- a/text/0000-prior-art.md +++ b/text/0000-prior-art.md @@ -130,6 +130,16 @@ review of prior art. Furthermore, this the changes to the template proposed in this RFC are by no means irreversible. If we find out after some time that this was a bad idea, we can always revert back to the way it was before. +Finally, a longer template risks making it harder to contribute to the +RFC process as an author as you are expected to fill in more sections. +Some people who don't know a lot of other langauges may be intimidated into +thinking that they are expected to know a wide variety of langauges and that +their contribution is not welcome otherwise. This drawback can be mitigated +by more clearly communicating that the RFC process is a collaborative effort. +If an author does not have prior art to offer up right away, other participants +in the RFC discussion may be able to provide such information which can then +be amended into the RFC. + # Rationale and alternatives [alternatives]: #alternatives From 9c8bdaa67ea9bc5eccaa62d22d101b5da72559d4 Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Tue, 27 Feb 2018 21:03:46 +0100 Subject: [PATCH 7/7] RFC 2333 --- text/{0000-prior-art.md => 2333-prior-art.md} | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) rename text/{0000-prior-art.md => 2333-prior-art.md} (98%) diff --git a/text/0000-prior-art.md b/text/2333-prior-art.md similarity index 98% rename from text/0000-prior-art.md rename to text/2333-prior-art.md index 22fa3ddd7..6934e52db 100644 --- a/text/0000-prior-art.md +++ b/text/2333-prior-art.md @@ -1,7 +1,7 @@ -- Feature Name: prior_art +- Feature Name: `prior_art` - Start Date: 2018-02-12 -- RFC PR: (leave this empty) -- Rust Issue: (leave this empty) +- RFC PR: [rust-lang/rfcs#2333](https://github.com/rust-lang/rfcs/pull/2333) +- Rust Issue: **self-executing** # Summary [summary]: #summary @@ -196,4 +196,4 @@ There are none as of yet. What is important in this RFC is that we establish whether we want a prior art section or not, and what it should contain in broad terms. -The exact language and wording can always be tweaked beyond this. \ No newline at end of file +The exact language and wording can always be tweaked beyond this.