bevyengine / rfcs Goto Github PK

It would be nice to be able to tell at a glance which designs still have work to do.

Folders is a decent approach to this, but we could also just use a file prefix.

See #1 for an example.

You need to point to the file in the branch of the originating fork. Use the label, not a specific commit, so it stays fresh.

This is useful for readers who prefer reading formatted markdown.

The master branch should be renamed to main to be consistent with Bevy's default branch and for the same reasons Bevy changed from master to main.

A terminology section would define jargon specific to an RFC.

A terminology helps RFC editing and reading:

• Helps the author re-use the same terms to refer to identical concepts
• Helps the author avoid mixing different ideas, on surface identical but not interchangeable
• Helps the author identify the concepts they are using and structure their explanation with clearly defined concepts in mind
• Helps the author limit how many different concepts they handle in the same RFC
• The reader can refer to that section if they forgot the meaning of a particularly specialized term
• The reader can pay closer attention to occurrence of terms specified in the terminology section
• It makes RFCs more accessible, as it introduces context and jargon that non-experts may not know

This is different from the "User-facing explanation" concept sub-section, in that the terminology section is for the terms used in the RFC rather than just the ones introduced into the user-facing API.

Alternative names for this section are

• Terminology
• Jargon
• syllabus
• nomenclature

As mentioned here by @DJMcNab, it may be beneficial to number RFCs, and would require little to no effort on the maintainers' side.

#2 (comment)

It's not just about uniqueness - it's useful for ordering/exploring.
Like low number RFCs are past and are expected to be somewhat outdated.
The numbering is assigned based on the GitHub pull request number, which means that
Ensuring that we increment numbers correctly / avoid collisions
is easy because GitHub handles it for us

For context, this is @cart's initial comment on RFC numbering:

bevyengine/bevy#1662 (comment)

I don't see much utility in numbering RFCs. We can already reference them via their "github issue number" and their "unique feature name" (which we require in the title). Ensuring that we increment numbers correctly / avoid collisions feels like wasted effort.