Conversation
template.md
Outdated
| - If applicable, explain how this feature compares to similar existing features, and in what situations the user would use each one. | ||
|
|
||
| ## Reference-level explanation | ||
| ## \[Optional\] Examples |
There was a problem hiding this comment.
I'm not sure we should encourage RFC developers to come up with complete self-contained examples (on top of the author-selected example snippets provided in the user-facing explanation):
- Coming up with a compilable example without an implementation of the feature to run through a compiler is a big ask
- Choosing the best holistic example to teach a given feature isn't necessarily the same as picking the best code snippets to introduce a feature in an RFC.
- Full examples do take up space and create new logistics problems like requiring collapsible sections.
To me this feels a bit like "additional" work that often can't be efficiently completed without a working impl. I'm pretty cool with just asking RFC implementers to come up with examples (when they are relevant).
There was a problem hiding this comment.
I agree with 1 and 2 for sure, and 3 can be a bit tricky. This is why I marked it as Optional; I think it's not a great fit for many RFCs but critical for others.
In particular, this was inspired by the UI work, where complex vertical slices are really important for seeing how everything fits together. I think this applies in a number of other domains too (e.g. physics, subworlds or scheduler APIs) where a lot of the challenge in a good design is in complexity management. The idea was to structure those slices by relating them to work that Bevy itself can use directly so then it doesn't go to waste.
People can always add bonus sections I guess, but I figured a cue and some concrete advice might be helpful for when it applies :)
Regardless on what we decide, I think the advice in this section on "What makes a good Bevy example" is valuable and if it doesn't end up here we should drop it in CONTRIBUTING.md or the like :)
There was a problem hiding this comment.
I think I'd prefer to just let this line from the "User-facing explanation" section to be open-ended based on the scope of the rfc: "Explaining the feature, ideally through simple examples of solutions to concrete problems."
Something like a UI RFC without UI examples isn't very useful, so we can/should encourage people to provide more examples where relevant.
My preference is to just remove the example section here and add the "what makes a good Bevy example" section to the Contributing section of the Bevy Book. I want to keep the RFC template "lean", and a large section requesting complete compilable / Bevy-example-folder-ready examples feels a bit "heavy", even if it has the optional label.
There was a problem hiding this comment.
Done. I think this should be ready to merge now then @cart.
|
In general I dig these changes. I'm just a little uncertain about the "examples" section (see my comment above). |
3 participants
RENDERED
I've worked with the RFC process a fair bit now, and while I generally like it, there are a few obvious warts that I'd like to get out of the way sooner than later.
The basic problems I'm trying to solve are:
This means that there's a rough mapping of sections onto durable work:
Everything else is ephemeral; preserved only to record why we made the decisions we did.