Thanks to visit codestin.com
Credit goes to github.com

Skip to content

New process: design proposal template #454

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.

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

Merged
merged 1 commit into from
Aug 21, 2023

Conversation

stasm
Copy link
Collaborator

@stasm stasm commented Aug 16, 2023

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 :)

@stasm stasm added the Agenda+ Requested for upcoming teleconference label Aug 18, 2023
@aphillips aphillips merged commit fe32b49 into unicode-org:main Aug 21, 2023
@stasm stasm deleted the design-proposal-template branch September 4, 2023 05:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Agenda+ Requested for upcoming teleconference
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants