Update the RFC template

[nrc]

Improve the RFC template by adding more metadata, making the structure more flexible, and tweaking some wording.

Note that this proposal uses the proposed template as a bootstrap example.

Rendered

[ehuss]

👍 I like the idea of combining and simplifying some of the sections.

[joshtriplett]

The label already covers this.

[nrc]

It does, but part of the motivation for these changes is so that the author can suggest the team via tooling without needing to have that access to GH, and so that once committed, we still have a tool-visible record of information that was in the PR in the document itself.

[joshtriplett]

Suggested change

	- RFC PR: [#0000](https://github.com/rust-lang/rfcs/pull/0000)
	- RFC PR: <https://github.com/rust-lang/rfcs/pull/0000>

[ehuss]

These won't render as links in the rendered book without angle brackets.

[joshtriplett]

Ah, fair enough. Editing.

[nrc]

Why do you prefer this syntax? ISTM that the original and the proposed change are GitHub-standard and clear and concise. Spelling out the whole link is less readable.

[joshtriplett]

I feel that the number is perfectly readable at the end of the URL. I also think it's nice to be able to see the repository at a glance. I'm trying to preserve the information that's already available in the existing version.

The existing version, with rust-lang/rfcs#0000, provides enough information to know at a glance where it's going; the URL also preserves that information. Just #0000 doesn't.

[nrc]

The usual GitHub convention is to use #nnn for issues and PRs in the same repo and org/repo#nnn for issues and PRs in other repos. That is what I was following here. (Note also, that since this is a link, the browser will show the URL on hover, and the fact that this is an RFC PR is shown on the left of the colon). If there is consensus that we need the repo info then I'd be happy to drop this change (it is very minor, after all). IMO having the full link is less readable than either the proposed or former versions.

[joshtriplett]

Suggested change

	- Tracking Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000)
	- Tracking Issue: <https://github.com/rust-lang/rust/issues/0000>

[joshtriplett]

I think "Why are existing solutions not good enough" should go in the alternatives section, not here.

"include data" is a higher bar than we have ever set for RFCs; by all means if someone has data they should include it, but for many RFCs there may not be a meaningful way to collect data short of a full user study.

[nrc]

The point I was trying to make is to discuss why any new feature is required, rather than why this proposal is better than an alternative (I guess 'do nothing' is always an alternative, but it always seems a bit forced).

The request for data is specially prefixed with "If possible" because it is a high bar and I hope makes clear that is not required, but I think suggesting it is useful as a way to at least make people think in concrete terms where possible rather than 'just vibes' type motivations.

[joshtriplett]

The existing "rationale and alternatives" section includes "- What is the impact of not doing this?", and I think that's been useful; I think explicitly asking for discussion of the null alternative would help even more. I don't think it's "forced", I think it's genuinely useful to talk about what happens if we don't make the change. It also goes along with things like "could this be done as a macro", or "could this language change be done as a library feature", or "could this standard library feature be a crate instead".

I think "Why are existing solutions not good enough?" feels like the wrong tone; it assumes that there are existing solutions, for instance.

[joshtriplett]

The request for data is specially prefixed with "If possible" because it is a high bar and I hope makes clear that is not required, but I think suggesting it is useful as a way to at least make people think in concrete terms where possible rather than 'just vibes' type motivations.

I would love to see text that attempts to get people thinking in meaningful-to-others terms rather than purely subjective ones. For instance:

• Keep in mind that questions of design can be subjective, and the readers and reviewers may not share your tastes. Try to explain the value of your proposed change in ways meaningful to a broad audience. If you have or can easily get supporting data, provide it (e.g. how widely used a pattern is or how commonly an option is used).

[joshtriplett]

I think the title should still include "alternatives". Or alternatively, we could have a separate section for alternatives. I think specifically calling for alternatives has produced thoughtful and helpful results on many RFCs.

[nrc]

I added a bullet point about alternatives, and I've reworded it slightly to try and make it clearer. I hope that is enough to discuss alternatives where appropriate. I agree discussing alternatives is useful, but it is not always appropriate, often leads to boilerplate answers, and I don't think it is more important than other aspects of rationale such as drawbacks or risks.

[joshtriplett]

There was a separate section for drawbacks, and I think that was useful. Risks would go in that section as well.

[nrc]

I agree it's useful, but IMO the cost of having multiple sections outweighs the benefit of the usefulness, especially as most of the usefulness can come from having good prose text. These is often overlap between drawbacks and alternatives and having a single section means you can just discuss it once, if that is the case.

[joshtriplett]

@nrc I understand the point you're making, but I still disagree; I feel that "drawbacks with this proposal" and "alternative proposals", while they have some overlap, would both suffer if combined, resulting in less encouragement to cover them each separately.

[joshtriplett]

I don't think we need this as a metadata field at the very top. We can just suggest in another section to add any other terms useful for people to search for.

[nrc]

The point in having it in metadata is to make it visible to tools (both before and after RFCs are accepted). I hope that we can use them to 'search by tag' rather than just searching for free text.

I did suggest we might want to move all metadata elsewhere in the document, do you prefer that?

[joshtriplett]

What tools do you have in mind, besides search engines and grep, both of which can find keywords anywhere in the document?

I'm also hoping any search we add can similarly find keywords anywhere in the document.

Anything up at the top of the document is more stuff people have to skim over before they reach the summary and other descriptive text.

[nrc]

I have two tools in mind: one is a bot that can set the team and labels on the PR from the team and keywords in the RFC text, thus relieving some need for triage. The second is an enhanced RFC book site, where one could browse RFCs with a given tag/keyword, see the keywords in an index of RFCs, as well as search explicitly for a keyword (e.g., there is a huge difference in the word 'trait' occuring in the text of an RFC and the word being an identified keyword, the latter implies this is an RFC about the trait system, the former could just be a casual mention). https://www.ncameron.org/rfcs/ is a prototype of this idea.

Anything up at the top of the document is more stuff people have to skim over before they reach the summary and other descriptive text.

Do you prefer having metadata at the end of the doc? Or in a horizontal table like Ember RFCs? Or after the summary? I totally agree that it's sub-optimal to have the metadata at the top, but wasn't sure which alternative to propose.

[joshtriplett]

I don't think this should go right up at the top either.

Also, we should take care to avoid creating an undue burden here: we should make it clear that you should include notable discussions you're aware of, but that you don't have to exhaustively list every time the topic came up. (Some topics have come up many dozens of times. A few samples should suffice in such cases.)

[nrc]

I'll try and clarify the text. Again the motivation for having it here is so that it is useful for tools, not just for humans to read.

[joshtriplett]

See above: which tools and for what use cases?

[apiraino]

@nrc this is an interesting proposal that received some praise 🙂 How far are we from agreeing here? just curious if there are there some important blockers

thanks for an update