Skip to content

Update RFC template #3982

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
clarfonthey wants to merge 1 commit into
base: master
Choose a base branch
from
+8 −4
Draft

Update RFC template #3982

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions 0000-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@ This section should explain this problem in detail, including necessary backgrou
It should also contain several specific use cases where this feature can help a user, and explain how it helps.
This can then be used to guide the design of the feature.

This section is one of the most important sections of any RFC, and can be lengthy.
It can be tempting to confuse *motivation* with *rationale*.
The motivation helps you understand what the problem is, and the explanation is the *proposed* solution.
After the solution is explained, you should take care to explain why *this* solution is the best one, in the rationale.
Comment on lines +21 to +22

@steffahn steffahn Jul 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea of pointing out that rationale is different from motivation.

At the same time, with this current text, it feels like you’re just repeating the things that are already clearly explained elsewhere. Right above this, there’s already

## Motivation
Any changes to Rust should focus on solving a problem that users of Rust are having.
This section should explain this problem in detail […]

so “The motivation helps you understand what the problem is” sounds a bit repetetive.

And further down in the template, there’s already

## Rationale and alternatives
- Why is this design the best in the space of possible designs?
[…]

so “After the solution is explained, you should take care to explain why this solution is the best one, in the rationale” sounds redundant as well.

IMHO make sense to point out here that – hey, make sure not to overlook that rationale goes down there into it’s own different section1 – if that avoids an otherwise common problem in RFCs, or at least confusion point in the writing process, but we don’t need to repeat defining what each section is about.

I think, it’s possible to even misunderstand this text as it is now: By not explicitly referring down to the “Rationale and alternatives” section, this last note about “After the solution is explained, you should …” might initially sound - to a reader of this template - like it’s listing this rationale as another thing that should be included here (in the motivation section) as well.

I also don’t understand the sentence “the explanation is the proposed solution”. I see the words, I’m not quite sure what they’re actually telling me. “The explanation” of what? The explanation of the problem – … – is the solution(?) The explanation of the solution – … – helps understand the problem(?) Or just: the proposed solution should be explained as well(?) Something else?

Footnotes

  1. I haven’t come up with an actual/concrete formulation of what to use, sorry. ↩

@joshtriplett joshtriplett Jul 8, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so “The motivation helps you understand what the problem is” sounds a bit repetetive.

Not all repetition is a bad thing. We don't necessarily optimize human communication, including documentation, for maximum non-redundancy. A limited amount of repetition can be a form of error-correcting code, and can help people understand things.


## Guide-level explanation
[guide-level-explanation]: #guide-level-explanation
Expand All @@ -44,16 +46,18 @@ This is the technical portion of the RFC. Explain the design in sufficient detai

The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.

## Drawbacks
[drawbacks]: #drawbacks
## Drawbacks and limitations
[drawbacks-and-limitations]: #drawbacks-and-limitations

Why should we *not* do this?
- What are the downsides to this particular approach?
- How will this change limit future changes?
Comment on lines -47 to +53

@steffahn steffahn Jul 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I like about “why should we not do this?” is that it challenges you to give a “positive” answer. You should try your best to already collect the best arguments for why not doing this is actually better.

When it’s more like “this is the ‘drawbacks’ section; please list ‘downsides’ here” - then I might feel more motivated to minimize the amount of downsides listed since - well - downsides are a bad thing, right?

I like the idea to consider limitations to future change and I can’t find that mentioned elsewhere yet! It seems vaguely related to “future possibilities” (kinda “future non-possibilities”?) but also different.

One problem with asking this question might be that RFC authors aren’t usually required to be those people who already have in mind all the - maybe wanted - future changes that could possibly be limited by a particular proposal. Though if they do know some, that’s a great thing to already include in the RFC (and if not, it’s also not a bad idea to talk to other people in advance in order to get some ideas).

@clarfonthey clarfonthey Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have been mulling this over for a bit, and there probably is a way to word this more positively, but I guess the main thing that's important here is for folks to really think about what the limits of the change are, and whether other features are still able to be present if this change is accepted.

In a real sense, it's kind of asking the author to use their imagination and think about the most out-there features that we could be doing instead of this one, and whether they could be done in addition to this feature.

That said, there are some cases where this is a truly negative case: for example, stuff like Freeze has usually been declined on the basis that libraries would start to care about Freeze as an API stability guarantee, whereas right now they don't. In the "why shouldn't we do this" case, you can be positive: yeah, we don't need to worry about that, it's great, but in most cases I'd imagine this discusses how many other desired features could fit along with this one, to discuss the drawbacks, which is mostly positive.

Not really sure what the best wording is, here.


## Rationale and alternatives
[rationale-and-alternatives]: #rationale-and-alternatives

- Why is this design the best in the space of possible designs?
- What other designs have been considered and what is the rationale for not choosing them?
- Note that the *lack* of a change is one of the possible designs.

@steffahn steffahn Jul 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this actually true though? “Possible designs” sounds to me like “possible designs that solve the problem”. Though admittedly, the explicit framing around a problem is newer than this section.

That is not to say I’m opposed to the idea of pointing out more clearly than currently the case, that “no change” is something that should be properly compared against in this rationale section. I am just wondering if this framing works best. Some more thoughts on that:

  1. It feels to me like Motivation, together with Drawbacks, might already contain all the pros and cons of the comparison between this proposal vs no change. On second thought - I guess the rationale is the place where you could make sure to argue why the benefits outweigh the drawbacks? Maybe motivation is a bit more qualitative, perhaps a bit more storytelling-esque whereas here you’re supposed to more wholistically quantify and compare? I don’t actually know the answers here, I’m trying to make more sense of the template myself now 😇

  2. I think listing “no change” explicitly as one of the “other designs” can also result in some meaningless boilerplate similar to the example you gave in the OP.

    Right now, a lot of RFCs just include drawbacks as "technically, it is bad to add a change" which I don't think is particularly useful

    I could anticipate boilerplate because the sentence before this line says “what other designs have been considered […]”, which means you should kinda explain/list examples in the design space (in order to then compare with them); and you don’t really need to explicitly list “no change” as an alternative when it’s always the baseline alternative to compare against, anyway.

  3. I’m also noticing that just below this line in the template comes the preexisting line of

    • What is the impact of not doing this?

    which is also relevant to the rationale of why the proposed change is better than not doing anything; and in my view fits in worse with the rest of these bullet points once “no change” is declared to be one of the “possible designs”.

@joshtriplett joshtriplett Jul 8, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this change is important: people should always consider and document the null alternative. The line below of "impact of not doing this" covers this as well. But in general, people get attached to the idea of their solution, and it's worth getting people to think carefully about what would actually happen in their problem domain if we decided not to make a change.

- What is the impact of not doing this?
- If this is a language proposal, could this be done in a library or macro instead? Does the proposed change make Rust code easier or harder to read, understand, and maintain?

Expand Down