Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2025-12-26 02:48:37 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Update the MSC template (#2296)

Browse source 
Tradeoffs->Alternatives, and kill the Conclusions section
This commit is contained in:
Richard van der Hoff 2019-09-18 01:39:40 +01:00 committed by GitHub
parent 2c88f02daa
commit 5d6113db1e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 18 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
proposals/0000-proposal-template.md
View file

@ -41,34 +41,17 @@ The template should have the following sections:
* **Introduction** - This should cover the primary problem and broad description of the solution.
* **Proposal** - The gory details of the proposal.
* **Tradeoffs** - Any items of the proposal that are less desirable should be listed here. Alternative
solutions to the same problem could also be listed here.
* **Potential issues** - This is where problems with the proposal would be listed, such as changes
that are not backwards compatible.
* **Alternatives** - This section lists alternative solutions to the same
problem which have been considered and dismsissed.
* **Security considerations** - Discussion of what steps were taken to avoid security issues in the
future and any potential risks in the proposal.
* **Conclusion** - A repeat of the problem and solution.
Furthermore, the template should not be required to be followed. However it is strongly recommended to
maintain some sense of consistency between proposals.
## Tradeoffs
*This is where alternative solutions could be listed. There's almost always another way to do things
and this section gives you the opportunity to highlight why those ways are not as desirable. The
argument made in this example is that all of the text provided by the template could be integrated
into the proposals introduction, although with some risk of losing clarity.*
Instead of adding a template to the repository, the assistance it provides could be integrated into
the proposal process itself. There is an argument to be had that the proposal process should be as
descriptive as possible, although having even more detail in the proposals introduction could lead to
some confusion or lack of understanding. Not to mention if the document is too large then potential
authors could be scared off as the process suddenly looks a lot more complicated than it is. For those
reasons, this proposal does not consider integrating the template in the proposals introduction a good
idea.
## Potential issues
*Not all proposals are perfect. Sometimes there's a known disadvantage to implementing the proposal,
@ -84,6 +67,22 @@ is beneficial and not considered a significant problem because it will lead to a
can follow.
## Alternatives
*This is where alternative solutions could be listed. There's almost always another way to do things
and this section gives you the opportunity to highlight why those ways are not as desirable. The
argument made in this example is that all of the text provided by the template could be integrated
into the proposals introduction, although with some risk of losing clarity.*
Instead of adding a template to the repository, the assistance it provides could be integrated into
the proposal process itself. There is an argument to be had that the proposal process should be as
descriptive as possible, although having even more detail in the proposals introduction could lead to
some confusion or lack of understanding. Not to mention if the document is too large then potential
authors could be scared off as the process suddenly looks a lot more complicated than it is. For those
reasons, this proposal does not consider integrating the template in the proposals introduction a good
idea.
## Security considerations
*Some proposals may have some security aspect to them that was addressed in the proposed solution. This
@ -94,20 +93,3 @@ of concerns where possible.*
By having a template available, people would know what the desired detail for a proposal is. This is not
considered a risk because it is important that people understand the proposal process from start to end.
## Conclusion
*Repeating the problem and solution in different words helps reviewers understand the problem a bit more.
This section should wrap up any loose ends left in the document, as well as cover a brief overview of the
content in each section. Note that the example here doesn't touch on the specific implementation details
described in the "Proposal" section - just the high-level points made there.*
Not having a template for people to follow when making their proposals could lead to large differences
between each MSC. This would make it difficult for reviewers, and there's a potential that some information
could be left out by accident. A template written in the same format the proposal process requires would
give authors the ability to understand how to better explain their own proposal.
A descriptive template would help potential authors comprehend what the proposal process requires by
demonstrating what is expected of a proposal. Although this is more effort up front, it would lead to more
time saved in the future due to questions about the process.