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
kegsay b873ba984c MSC2946: Spaces Summary (#2946)
* Spaces Summary

* MSC2946

* Clarity

* More clarity

* Clarify what no room data means for clients

* Federation API

* Update 2946-spaces-summary.md

* auto_join filter

* Blurb on auth for fed api

* Update to reflect MSC1772 changes

* Mention auth chain on federation api

* Add 'version' field

* Stripped state; remove room versions

* Update 2946-spaces-summary.md

* Update proposals/2946-spaces-summary.md

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>

* Replace with link to draft doc.

* Add a preamble and copy the current draft API.

* Switch to using stable identifiers (and add an unstable identifiers section).

* Updates / clarifications.

* Fix typo.

* Clean-ups.

* Update proposals/2946-spaces-summary.md

Co-authored-by: Travis Ralston <travpc@gmail.com>

* Drop unstable identifiers from MSC1772.

* Various updates and clarifications.

* Include the origin_server_ts in the response, as needed by MSC1772.

* Rename a parameter for clarity.

* Fix typo.

Co-authored-by: David Baker <dbkr@users.noreply.github.com>

* Various clarifications based on feedback.

* Add auth / rate-limiting info.

* Combine some double spaces.

* Use only GET endpoints.

* Add notes about DoS potential.

* Tweaks from review.

* Add context about why stripped events are returned.

* Remove some implementation details.

* Add notes on ordering.

* Remove unnecessary data.

* Clarify the server-server API.

* More clarifications.

* Remove obsolete note.

* Some clarifications to what accessible means.

* Update notes about sorting to include the origin_server_ts of the m.space.child event.

This reverts commit af8c7b04d9.

* Only consider `m.space` rooms and do not return links to nowhere.

* Updates based on MSC3173 merging and updates to MSC3083.

* Updates per MSC2403.

* Remove field which is not part of the C-S API.

* Rewrite the proposal.

* Handle todo comments.

* Update URLs.

* Rename field.

* Updates based on implementation.

* Clarify the state which is persisted.

* Expand notes about errors.

* Update MSC with pagination parameter.

* Fix wrong endpoint.

Co-authored-by: Matthew Hodgson <matthew@matrix.org>

* Clarifications based on implementation.

* Remove empty section.

* Fix typo.

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Rename field in example.

* Clarify error code.

* Clarify ordering changes.

* Clarify wording.

Co-authored-by: Travis Ralston <travisr@matrix.org>

* Fix typos.

Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>

* Clarify that rooms do not belong to servers.

Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>

* Fix example to use correct URL.

Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>

* Clarify using local vs. remote data.

Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>

* Clarify bits aboud stripped state.

* Clarify access control of federation responses.

* Clarify error code.

Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>

* Be less prescriptive about expiring data.

* Limit must be non-zero.

Co-authored-by: Travis Ralston <travisr@matrix.org>

* Rate limiting.

Co-authored-by: Travis Ralston <travisr@matrix.org>

* Add a note about room upgrades.

* Update stable URLs per MSC2844.

* Clarify federation return values.

* Clarify `origin_server_ts`.

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>

* Tweak wording around `inaccessible_children`.

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <richard@matrix.org>
Co-authored-by: Patrick Cloke <patrickc@matrix.org>
Co-authored-by: Matthew Hodgson <matthew@matrix.org>
Co-authored-by: Travis Ralston <travpc@gmail.com>
Co-authored-by: David Baker <dbkr@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Co-authored-by: Travis Ralston <travisr@matrix.org>
Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>
Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
3 years ago
.circleci Remove all references to speculator (#3430) 3 years ago
.github Add github action to build release tags (#3449) 3 years ago
assets-hugo Fix sidebar overlap for small width devices 3 years ago
attic Add proto-MSC on the design of URL previews. (#3378) 3 years ago
changelogs Update identity server spec to use global versioning (#3459) 3 years ago
content fix typo: word plural 3 years ago
data Update identity server spec to use global versioning (#3459) 3 years ago
data-definitions Update sas-emoji.json 3 years ago
informal Apply suggestions from code review 3 years ago
layouts Release process: changelog generation and docs (#3446) 3 years ago
meta Release process: changelog generation and docs (#3446) 3 years ago
proposals MSC2946: Spaces Summary (#2946) 3 years ago
scripts Release process: changelog generation and docs (#3446) 3 years ago
static Add knocking to the spec 3 years ago
themes Opt for serving new spec JS/CSS dependencies locally instead of downloading from CDNs (#3036) 3 years ago
.gitignore Release process: changelog generation and docs (#3446) 3 years ago
.gitmodules Opt for serving new spec JS/CSS dependencies locally instead of downloading from CDNs (#3036) 3 years ago
CONTRIBUTING.rst Switch code formatting note about changelogs from RST to MD (#3103) 3 years ago
LICENSE Add a license to the spec 8 years ago
README.md Notes on how to use `hugo` from docker (#3349) 3 years ago
config-circleci.toml Update CircleCI and Buildkite configs to build the new spec (#3017) 3 years ago
config.toml Use `changelogs/release.yaml` for the version number source everywhere (#3310) 3 years ago
openapi_extensions.md Start annotating which version of the spec added a thing (#3425) 3 years ago
package-lock.json Bump ansi-regex from 5.0.0 to 5.0.1 (#3444) 3 years ago
package.json Support rendering of proposal tables 3 years ago
pyproject.toml goodbye legacy config 3 years ago

README.md

Matrix Specification

This repository contains the Matrix Specification, rendered at spec.matrix.org.

Developers looking to use Matrix should join #matrix-dev:matrix.org on Matrix for help.

Spec authors and proposal writers are welcome to join #matrix-spec:matrix.org. We welcome contributions! See CONTRIBUTING.rst for details.

Structure

The Matrix spec is compiled with Hugo (a static site generator) with the following structure:

  • /assets: assets that need postprocessing using Hugo Pipes. For example, Sass files would go here.

  • /content: files that will become pages in the site go here. Typically these are Markdown files with some YAML front matter indicating, among other things, what layout should be applied to this page. The organization of files under /content determines the organization of pages in the built site.

  • /data: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as data objects, so templates don't need to load them from a file and parse them. This is also where our Swagger/OpenAPI definitions and schemas are.

  • /layouts: this contains Hugo templates. Some templates define the overall layout of a page: for example, whether it has header, footer, sidebar, and so on.

    • /layouts/partials: these templates can be called from other templates, so they can be used to factor out template code that's used in more than one template. An obvious example here is something like a sidebar, where several different page layouts might all include the sidebar. But also, partial templates can return values: this means they can be used like functions, that can be called by multiple templates to do some common processing.
    • /layouts/shortcodes: these templates can be called directly from files in /content.
  • /static: static files which don't need preprocessing. JS or CSS files could live here.

  • /themes: you can use just Hugo or use it with a theme. Themes primarily provide additional templates, which are supplied in a /themes/$theme_name/layouts directory. You can use a theme but customise it by providing your own versions of any of the theme layouts in the base /layouts directory. That is, if a theme provides /themes/$theme_name/layouts/sidebar.html and you provide /layouts/sidebar.html, then your version of the template will be used.

It also has the following top-level file:

  • config.toml: site-wide configuration settings. Some of these are built-in and you can add your own. Config settings defined here are available in templates. All these directories above are configurable via config.toml settings.

Additionally, the following directories may be of interest:

  • /attic: Here contains historical sections of specification and legacy drafts for the specification.
  • /changelogs: Various bits of changelog for the specification areas.
  • /data-definitions: Bits of structured data consumable by Matrix implementations.
  • /meta: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc).
  • /scripts: Various scripts for generating the spec and validating its contents.
  • /proposals: Matrix Spec Change (MSC) proposals. See https://spec.matrix.org/unstable/proposals/.

Authoring changes to the spec

Please read CONTRIBUTING.rst before authoring a change to the spec. Note that spec authoring takes place after an MSC has been accepted, not as part of a proposal itself.

  1. Install the extended version (often the OS default) of Hugo: https://gohugo.io/getting-started/installing. Note that at least Hugo v0.74 is required.

    Alternatively, use the Docker image at https://hub.docker.com/r/klakegg/hugo/.

  2. Run git submodule update --init --recursive for good measure.

  3. Run npm i to install the dependencies. Note that this will require NodeJS to be installed.

  4. Run npm run get-proposals to seed proposal data. This is merely for populating the content of the "Spec Change Proposals" page and is not required.

  5. Run hugo serve (or docker run --rm -it -v $(pwd):/src -p 1313:1313 klakegg/hugo serve) to run a local webserver which builds whenever a file change is detected. If watching doesn't appear to be working for you, try adding --disableFastRender to the commandline.

  6. Edit the specification 🙂

We use a highly customized Docsy theme for our generated site, which uses Bootstrap and Font Awesome. If you're looking at making design-related changes to the spec site, please coordinate with us in #matrix-docs:matrix.org before opening a PR.

Building the specification

If for some reason you're not a CI/CD system and want to render a static version of the spec for yourself, follow the above steps for authoring changes to the specification and instead of hugo serve run hugo -d "spec" - this will generate the spec to /spec. If you'd like to serve the spec off a path instead of a domain root (eg: /unstable), add --baseURL "/unstable" to the hugo -d "spec" command.

For building the swagger definitions, create a python3 virtualenv and activate it. Then run pip install -r ./scripts/requirements.txt and finally python ./scripts/dump-swagger.py to generate it to ./scripts/swagger/api-docs.json. To make use of the generated file, there are a number of options:

Issue tracking

Specification issues are tracked on github at https://github.com/matrix-org/matrix-doc/issues.

See meta/github-labels.rst for information on what the labels mean.