0000-proposal-template.md (6765B)
1 # MSC0000: Template for new MSCs 2 3 *Note: Text written in italics represents notes about the section or proposal process. This document 4 serves as an example of what a proposal could look like (in this case, a proposal to have a template) 5 and should be used where possible.* 6 7 *In this first section, be sure to cover your problem and a broad overview of the solution. Covering 8 related details, such as the expected impact, can also be a good idea. The example in this document 9 says that we're missing a template and that things are confusing and goes on to say the solution is 10 a template. There's no major expected impact in this proposal, so it doesn't list one. If your proposal 11 was more invasive (such as proposing a change to how servers discover each other) then that would be 12 a good thing to list here.* 13 14 *If you're having troubles coming up with a description, a good question to ask is "how 15 does this proposal improve Matrix?" - the answer could reveal a small impact, and that is okay.* 16 17 There can never be enough templates in the world, and MSCs shouldn't be any different. The level 18 of detail expected of proposals can be unclear - this is what this example proposal (which doubles 19 as a template itself) aims to resolve. 20 21 22 ## Proposal 23 24 *Here is where you'll reinforce your position from the introduction in more detail, as well as cover 25 the technical points of your proposal. Including rationale for your proposed solution and detailing 26 why parts are important helps reviewers understand the problem at hand. Not including enough detail 27 can result in people guessing, leading to confusing arguments in the comments section. The example 28 here covers why templates are important again, giving a stronger argument as to why we should have 29 a template. Afterwards, it goes on to cover the specifics of what the template could look like.* 30 31 Having a default template that everyone can use is important. Without a template, proposals would be 32 all over the place and the minimum amount of detail may be left out. Introducing a template to the 33 proposal process helps ensure that some amount of consistency is present across multiple proposals, 34 even if each author decides to abandon the template. 35 36 The default template should be a markdown document because the MSC process requires authors to write 37 a proposal in markdown. Using other formats wouldn't make much sense because that would prevent authors 38 from copy/pasting the template. 39 40 The template should have the following sections: 41 42 * **Introduction** - This should cover the primary problem and broad description of the solution. 43 * **Proposal** - The gory details of the proposal. 44 * **Potential issues** - This is where problems with the proposal would be listed, such as changes 45 that are not backwards compatible. 46 * **Alternatives** - This section lists alternative solutions to the same 47 problem which have been considered and dismsissed. 48 * **Security considerations** - Discussion of what steps were taken to avoid security issues in the 49 future and any potential risks in the proposal. 50 51 Furthermore, the template should not be required to be followed. However it is strongly recommended to 52 maintain some sense of consistency between proposals. 53 54 55 ## Potential issues 56 57 *Not all proposals are perfect. Sometimes there's a known disadvantage to implementing the proposal, 58 and they should be documented here. There should be some explanation for why the disadvantage is 59 acceptable, however - just like in this example.* 60 61 Someone is going to have to spend the time to figure out what the template should actually have in it. 62 It could be a document with just a few headers or a supplementary document to the process explanation, 63 however more detail should be included. A template that actually proposes something should be considered 64 because it not only gives an opportunity to show what a basic proposal looks like, it also means that 65 explanations for each section can be described. Spending the time to work out the content of the template 66 is beneficial and not considered a significant problem because it will lead to a document that everyone 67 can follow. 68 69 70 ## Alternatives 71 72 *This is where alternative solutions could be listed. There's almost always another way to do things 73 and this section gives you the opportunity to highlight why those ways are not as desirable. The 74 argument made in this example is that all of the text provided by the template could be integrated 75 into the proposals introduction, although with some risk of losing clarity.* 76 77 Instead of adding a template to the repository, the assistance it provides could be integrated into 78 the proposal process itself. There is an argument to be had that the proposal process should be as 79 descriptive as possible, although having even more detail in the proposals introduction could lead to 80 some confusion or lack of understanding. Not to mention if the document is too large then potential 81 authors could be scared off as the process suddenly looks a lot more complicated than it is. For those 82 reasons, this proposal does not consider integrating the template in the proposals introduction a good 83 idea. 84 85 86 ## Security considerations 87 88 *Some proposals may have some security aspect to them that was addressed in the proposed solution. This 89 section is a great place to outline some of the security-sensitive components of your proposal, such as 90 why a particular approach was (or wasn't) taken. The example here is a bit of a stretch and unlikely to 91 actually be worthwhile of including in a proposal, but it is generally a good idea to list these kinds 92 of concerns where possible.* 93 94 By having a template available, people would know what the desired detail for a proposal is. This is not 95 considered a risk because it is important that people understand the proposal process from start to end. 96 97 ## Unstable prefix 98 99 *If a proposal is implemented before it is included in the spec, then implementers must ensure that the 100 implementation is compatible with the final version that lands in the spec. This generally means that 101 experimental implementations should use `/unstable` endpoints, and use vendor prefixes where necessary. 102 For more information, see [MSC2324](https://github.com/matrix-org/matrix-doc/pull/2324). This section 103 should be used to document things such as what endpoints and names are being used while the feature is 104 in development, the name of the unstable feature flag to use to detect support for the feature, or what 105 migration steps are needed to switch to newer versions of the proposal.* 106 107 ## Dependencies 108 109 This MSC builds on MSCxxxx, MSCyyyy and MSCzzzz (which at the time of writing have not yet been accepted 110 into the spec).