Proposals for changes to the matrix specification
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
Richard van der Hoff 834a3d78a8 Add a pip requirements file for the scripts 7 years ago
api Move the MXID spec to the appendices 7 years ago
attic Consistently spell homeserver as homeserver 9 years ago
changelogs changelog 7 years ago
drafts Delete state_resolution.rst 7 years ago
event-schemas Merge pull request #1026 from matrix-org/rav/power_levels_doc 7 years ago
meta Link to doc style doc 8 years ago
scripts Add a pip requirements file for the scripts 7 years ago
specification Merge branch 'client_server/r0.2.0_updates' 7 years ago
supporting-docs Neo update 7 years ago
templating Clarify what happens when there is no power_levels event 7 years ago
.gitignore Update .gitignore 7 years ago
CONTRIBUTING.rst Link to doc style doc 8 years ago
LICENSE Add a license to the spec 8 years ago
README.rst move issue info to bottom of readme 7 years ago
jenkins.sh Add a pip requirements file for the scripts 7 years ago

README.rst

This repository contains the documentation for Matrix.

Primarily, that means the Matrix protocol specifcation, but this repo also
comtains a lot of supporting documents, including some introductions to Matrix,
and, notably, a list of projects using Matrix which is visible on the
`matrix.org website <https://matrix.org/docs/projects/try-matrix-now.html>`_.

Structure of this repository
============================

- ``api`` : `OpenAPI`_ (swagger) specifications for the the HTTP APIs.
- ``attic``: historical sections of specification for reference
  purposes.
- ``changelogs``: change logs for the various parts of the
  specification.
- ``drafts``: Previously, contained documents which were under discussion for
  future incusion into the specification and/or supporting documentation. This
  is now historical, as we use separate discussion documents (see
  `<CONTRIBUTING.rst>`_).
- ``event-schemas``: the `JSON Schema`_ for all Matrix events
  contained in the specification, along with example JSON files.
- ``meta``: documents outlining the processes involved when writing
  documents, e.g. documentation style, guidelines.
- ``scripts``: scripts to generate formatted versions of the
  documentation, typically HTML.
- ``specification``: the specification split up into sections.
- ``supporting-docs``: additional documents which explain design
  decisions, examples, use cases, etc.
- ``templating``: the templates and templating system used to
  generate the spec.

.. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
.. _JSON Schema: http://json-schema.org/

Contributing
============

If you want to ask more about the specification, join us on
`#matrix-dev:matrix.org <http://matrix.to/#/#matrix-dev:matrix.org>`_.

If you would like to contribute to the specification or supporting
documentation, see `<CONTRIBUTING.rst>`_.

Issue tracking
==============

Issues with the Matrix specification and supporting documentation are tracked
in `GitHub <https://github.com/matrix-org/matrix-doc/issues>`_.

The following labels are used to help categorize issues:

`spec-omission <https://github.com/matrix-org/matrix-doc/labels/spec-omission>`_
--------------------------------------------------------------------------------

Things which have been implemented but not currently specified. These may range
from entire API endpoints, to particular options or return parameters.

Issues with this label will have been implemented in `Synapse
<https://github.com/matrix-org/synapse>`_. Normally there will be a design
document in Google Docs or similar which describes the feature.

Examples:

* `Spec PUT /directory/list <https://github.com/matrix-org/matrix-doc/issues/417>`_
* `Unspec'd server_name request param for /join/{roomIdOrAlias}
  <https://github.com/matrix-org/matrix-doc/issues/904>`_

`clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
--------------------------------------------------------------------------------

An area where the spec could do with being more explicit.

Examples:

* `Spec the implicit limit on /syncs
  <https://github.com/matrix-org/matrix-doc/issues/708>`_

* `Clarify the meaning of the currently_active flags in presence events
  <https://github.com/matrix-org/matrix-doc/issues/686>`_

`bug <https://github.com/matrix-org/matrix-doc/labels/bug>`_
------------------------------------------------------------

Something which is in the spec, but is wrong.

Note: this is *not* for things that are badly designed or don't work well
(for which see 'improvement' or 'feature') - it is for places where the
spec doesn't match reality.

Examples:

* `swagger is wrong for directory PUT
  <https://github.com/matrix-org/matrix-doc/issues/933>`_

* `receipts section still refers to initialSync
  <https://github.com/matrix-org/matrix-doc/issues/695>`_

`improvement <https://github.com/matrix-org/matrix-doc/labels/improvement>`_
----------------------------------------------------------------------------

A suggestion for a relaatively simple improvement to the protocol.

Examples:

* `We need a 'remove 3PID' API so that users can remove mappings
  <https://github.com/matrix-org/matrix-doc/issues/620>`_
* `We should mandate that /publicRooms requires an access_token
  <https://github.com/matrix-org/matrix-doc/issues/612>`_

`feature <https://github.com/matrix-org/matrix-doc/labels/feature>`_
--------------------------------------------------------------------

A suggestion for a significant extension to the matrix protocol which
needs considerable consideration before implementation.

Examples:

* `Peer-to-peer Matrix <https://github.com/matrix-org/matrix-doc/issues/710>`_
* `Specify a means for clients to "edit" previous messages
  <https://github.com/matrix-org/matrix-doc/issues/682>`_

`projects <https://github.com/matrix-org/matrix-doc/labels/projects>`_
----------------------------------------------------------------------

A project which needs adding to the 'Try Matrix Now' page.

Examples:

* `add https://gitlab.com/uhoreg/matrix-appservice-prosody
  <https://github.com/matrix-org/matrix-doc/issues/1016>`_

* `add https://github.com/tavoda/matrix-java project
  <https://github.com/matrix-org/matrix-doc/issues/956>`_

`site <https://github.com/matrix-org/matrix-doc/labels/site>`_
--------------------------------------------------------------

Ideas for things to help document or sell matrix more generally.
(Probably these would be better filed under
https://github.com/matrix-org/matrix.org, but they tend to end up here.)