matrix-org / matrix-org/matrix-spec

Move definitions of event and account_data schemas out of the C-S spec

Open
#896 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

The client-server spec contains definitions of many different event types, scattered throughout the document:
* https://spec.matrix.org/unstable/client-server-api/#room-events
* https://spec.matrix.org/unstable/client-server-api/#events-1
* https://spec.matrix.org/unstable/client-server-api/#events-2
* https://spec.matrix.org/unstable/client-server-api/#events-3
* https://spec.matrix.org/unstable/client-server-api/#events-8
* https://spec.matrix.org/unstable/client-server-api/#events-9
* https://spec.matrix.org/unstable/client-server-api/#events-10
* https://spec.matrix.org/unstable/client-server-api/#events-11
* https://spec.matrix.org/unstable/client-server-api/#events-16
* https://spec.matrix.org/unstable/client-server-api/#events-17
* https://spec.matrix.org/unstable/client-server-api/#events-18
* https://spec.matrix.org/unstable/client-server-api/#events-19
* (and probably others)

I think it's confusing that we conflate the mechanism for sending and receiving events (the C-S API) with the events that can be sent. Furthermore:
* In most cases servers don't actually care about the events at all.
* These event definitions are a significant part of the length of the C-S spec, and their inclusion there makes it hard to understand and navigate the C-S spec
* It's also hard to find the definition of a given event type.
* This is less of an argument now than it used to be, thanks to [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844), but adding new event types shouldn't need changes to the C-S spec.

I think we could also make a similar argument for account data types (https://spec.matrix.org/unstable/client-server-api/#midentity_server, https://spec.matrix.org/unstable/client-server-api/#events-6, https://spec.matrix.org/unstable/client-server-api/#key-storage, https://spec.matrix.org/unstable/client-server-api/#events-14, etc).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the client-server API sections linked in the issue, including Room Events, Events 1–3 and 8–19, plus the linked account-data sections and MSC2844. Define a separate location for event and account-data schemas while preserving the C-S API's event transport documentation; done means the definitions are no longer scattered through the C-S spec and remain discoverable.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.