Researching for a Matrix Spec Change

The Matrix protocol is modified via Matrix Spec Changes (frequently abbreviated to “MSCs”). These are short documents describing any technical changes and why they are worth making (see an example). I’ve written a bunch and wanted to document my research process. [1]

First, I write out a problem statement: what am I trying to solve? (This step might seem obvious, but it is useful to frame the technical changes in why they matter. Many proposals seem to skip this step.) Most of my work tends to be from the point of view of an end-user, but some changes are purely technical. Regardless, there is benefit from a shared written context of the issue to be solved.

From the above and prior knowledge, I list any open questions (which I update through this process). I’ll augment the questions with answers I find in my research, write new ones about things I don’t understand, or remove them as they become irrelevant.

Next, I begin collecting any previous work done in this area, including:

• What is the current specification related to this? I usually pull out blurbs (with links back to the source) from the latest specification.

• Are there any related known issues? It is also worth checking the issue trackers of projects: I start with the Synapse, Element Meta, and Element Web repositories.

• Are there related outstanding MSCs or previous research? I search the matrix-spec-proposals repository for keywords, open anything that looks vaguely related and then crawl those for mentions of other MSCs. I’ll document the related ones with links and a brief description of the proposed change.

  I include both proposed and closed MSCs to check for previously rejected ideas.

• Are others interested in this? Have others had conversation about it? I roughly follow the #matrix-spec room or search for rooms that might be interested in the topic. I would recommend joining the #matrix-spec room for brainstorming and searching.

  This step can help uncover any missed known issues and MSCs. I will also ask others with a longer history in the project if I am missing anything.

• A brief competitive analysis is performed. Information can be gleaned from technical blog posts and API documentation. I consider not just competing products, but also investigate if others have solved similar technical problems. Other protocols are worth checking (e.g. IRC, XMPP, IMAP).

You can see an example of my research on Matrix read receipts & notifications.

Once I have compiled the above information, I jump into the current implementation to ensure it roughly matches the specification. [2] I start considering what protocol changes would solve the problem and are reasonable to implement. I find it useful to write down all of my ideas, not just the one I think is best. [3]

At this point I have:

• A problem statement
• A bunch of background about the current protocol, other proposed solutions, etc.
• A list of open questions
• Rough ideas for proposed solutions

The next step is to iterate with my colleagues: answer any open questions, check that our product goals will be met, and seek agreement that we are designing a buildable solution. [4]

Finally, I take the above and formalize it in into one or more Matrix Spec Changes. At this point I’ll think about error conditions / responses, backwards compatibility, security concerns, and any other parts of the full MSC. Once it is documented, I make a pull request with the proposal and self-review it for loose ends and clarity. I leave comments for any parts I am unsure about or want to open discussion on.

Then I ask me colleagues to read through it and wait for feedback from both them and any interested community members. It can be useful to be in the #matrix-spec room as folks might want to discuss the proposal.