From 5d6113db1ec97052d74f271ceb7adb11a9f84787 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 18 Sep 2019 01:39:40 +0100 Subject: [PATCH] Update the MSC template (#2296) Tradeoffs->Alternatives, and kill the Conclusions section --- proposals/0000-proposal-template.md | 54 ++++++++++------------------- 1 file changed, 18 insertions(+), 36 deletions(-) diff --git a/proposals/0000-proposal-template.md b/proposals/0000-proposal-template.md index 8c8cdcea1..cf79ed99e 100644 --- a/proposals/0000-proposal-template.md +++ b/proposals/0000-proposal-template.md @@ -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.