New process: design proposal template #454
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I'd like to suggest a new process for discussing and designing features and changes to MF2: document the design in a single Markdown file before implementing it in the spec.
Today, the scope and the specification of MF2 are concrete enough to be a good base against which incremental designs can be evaluated. MF2 is also complex enough to require a good deal of consideration of how a newly introduced change interacts with other parts of the standard.
In particular, I think such documents would be the right place to gather use-cases and requirements in a way that (a) allows us to evaluate alternative designs, and (b) can be looked up in the future to understand what problem we wanted to solve.
New proposals would be made in form of PRs adding a new file to the
exploration
directory. (The number in the file name is the PR's number, which requires a little bit of extra effort but will help with ordering and avoiding file naming conflicts.) The discussion follows in PR's review comments. When the PR is merged, it means that the proposal can be implemented in the spec. The implementation can itself result in more discussion; sometimes certain proposal will need to be reverted.How is this different from opening new issues with a similar template to the one I propose here? There's one crucial difference: when the proposal PR is merged, the merged document represents the up-to-date consensus. With issues, the consensus is spread across multiple comments or sometimes multiple issues, making it hard to reason about some changes after time has passed.
Not all discussions nor changes need to go through this new process. I don't know exactly what criteria to use to decide whether a change needs a design proposal doc or not. Instead I suggest a heuristic: when a reviewer says that a change would benefit from a design proposal doc, it means that it needs one :)