feat(decision-process): record decisions surfaced during RFC review - #154
Conversation
As part of an RFC review, some decisions may come to light that relate to the expected outcome of the RFC. At present these can get lost inside PR comments or Slack threads without a formal record being made. To improve discoverability, RFCs may now carry an optional `## Decisions` section with dated `### YYYY-MM-DD Title` entries recorded before approval. The format checker validates the section when present and exports the decisions into the rendered JSON so they surface in the handbook. Existing RFCs are unaffected; the section is optional and not back-ported.
There was a problem hiding this comment.
Should we make the Decisions section mandatory? I think we should, as from each RFC there should come some decisions, even when they are of negative type, like "Decision: do not add orange juice to clusters".
By mandatory, I mean validate in the process automatio that it exists.
|
|
||
| ### YYYY-MM-DD The decision, stated in the heading | ||
|
|
||
| Context and reasoning behind the decision. |
There was a problem hiding this comment.
Do we want the context here? I think the context should be already given earlier, to start the Comments process, and here we want to have the gist of decisions taken. WDYT?
There was a problem hiding this comment.
I think this is just a change of word from Context to Description
|
I left the Decisions block optional because it will not apply to every RFC. Some may be accepted without additional decisions whilst others may have a plethora of them. I think this is the safest way to ensure compatibility across all RFC types. |
|
Would it be more clear to write something along the lines of:
That way it's clear when to add the block. Just declaring it optional may leave too much to chance. (Imagine a contemporary LLM reading and acting on it.) |
|
Where should decision go that come up after it was approved / merged? For example something comes up during implementation or smaller changes later? Should the original RFC be extended? For example the semver based upgrade RFC was nicely updated / ported back 3 times after it was merged:
This also leads to the question if it is still okay to extend / update the content or should it always go to the Decisions block? |
|
i reckon this is good enough to get started with. i could make up examples of RFCs that may not need / want a decisions section, so i'm fine w/ optional. with decisions made after the rfc is approved / merged, i think a follow up PR is fine, we're definitely going to have situations where we "miss" something |
5 participants
As part of an RFC review, some decisions may come to light that relate to the expected outcome of the RFC. At present these can get lost inside PR comments or Slack threads without a formal record being made.
To improve discoverability, RFCs may now carry an optional
## Decisionssection with dated### YYYY-MM-DD Titleentries recorded before approval. The format checker validates the section when present and exports the decisions into the rendered JSON so they surface in the handbook.Existing RFCs are unaffected; the section is optional and not back-ported.