f97d2944ae
Some checks failed
Spec / 🔎 Validate OpenAPI specifications (push) Has been cancelled
Spec / 🔎 Check Event schema examples (push) Has been cancelled
Spec / 🔎 Check OpenAPI definitions examples (push) Has been cancelled
Spec / 🔎 Check JSON Schemas inline examples (push) Has been cancelled
Spec / ⚙️ Calculate baseURL for later jobs (push) Has been cancelled
Spec / 📢 Run towncrier for changelog (push) Has been cancelled
Spell Check / Spell Check with Typos (push) Has been cancelled
Spec / 🐍 Build OpenAPI definitions (push) Has been cancelled
Spec / 📖 Build the spec (push) Has been cancelled
Spec / 🔎 Validate generated HTML (push) Has been cancelled
Spec / 📖 Build the historical backup spec (push) Has been cancelled
* Placeholder * i++ * Room version 12 Template out a v12 room version Make v12 default, per MSC4304 Update PDU checks and auth event selection per MSC4291 Describe new room_id format per MSC4291 Move v6 depth definition to a component for easier referencing Move room_id to a component to prep for v12, per MSC4291 Create and use a new room_id component for v12+ per MSC4291 Reflect auth events selection change onto all room versions per MSC4291 The MSC asks the `description` of `auth_events` to be adjusted, however this feels like a better representation of the change. Add `room_id` format rules and renumber per MSC4291 Reflect change to rule 1.2 per MSC4291 Insert same room_id check to v1-12 auth rules per MSC4307 and MSC4291 Deprecate `predecessor.event_id` per MSC4291 Insert auth rule to validate `additional_creators` per MSC4289 Insert rule for `users` validation of creators and renumber per MSC4289 Define "room creator(s)" per MSC4289 Spec `additional_creators` on create events per MSC4289 Spec `additional_creators` on `/upgrade` per MSC4289 The MSC doesn't mention how to handle unsupported room versions, but the Synapse implementation used for FCP ignores the field in such room versions. This feels like a good approach, and will need clarifying in the MSC too (if accepted at the spec level). Add notes to `/upgrade` behaviour per MSC4289 and MSC4291 Describe how additional creators work during room creation per MSC4289 Fix default user power level descriptions per MSC4289 Describe tombstone power level changes per MSC4289 Warn clients about event format changes in v12 per MSC4289 and MSC4291 Flag additional room creators support for client reference per MSC4289 Remove TODO now that it's fully addressed Copy state res into v12 as-is for modification Apply Modification 1 to SR2.1 per MSC4297 Apply Modification 2 to SR2.1 per MSC4297 Add summary box to the top of SR2.1 for ease of developer reference Modification 2 was split into items 2 and 3 for further ease of understanding. Add all the changelogs `x` is used until a real PR number can be assigned. Some changelogs are duplicated to the Client-Server API to increase visibility of the changes to v12. Review: Minor phrasing adjustments in changelogs Review: Clarify that v12 isn't quite the default yet in the changelog Review: Clarify to clients that creators are immutable Review: Improve 'how to parse a domain' advice for legacy apps Review: Add a bit more detail as to why a room ID might be required Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Clarify that clients can override the tombstone default Mention creatorship UI label by finishing the Permissions section We probably should have removed the WIP note in v1.0, but alas. Add changelog for tombstone changes Use assigned spec PR number in changelogs (cherry picked from commit ec81eea7e4532fd398b8013071d6981c97117d9e) |
||
|---|---|---|
| .github | ||
| assets | ||
| attic | ||
| changelogs | ||
| config | ||
| content | ||
| data | ||
| data-definitions | ||
| informal | ||
| layouts | ||
| meta | ||
| packages/npm | ||
| scripts | ||
| static | ||
| .gitignore | ||
| .htmltest.yml | ||
| CONTRIBUTING.rst | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| openapi_extensions.md | ||
| package-lock.json | ||
| package.json | ||
| postcss.config.js | ||
| README.md | ||
| redocly.yaml | ||
Matrix Specification
This repository contains the Matrix Specification. The current release version is rendered at https://spec.matrix.org, while the latest available build of the main branch is at https://spec.matrix.org/unstable.
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/contentdetermines 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 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/layoutsdirectory. You can use a theme but customise it by providing your own versions of any of the theme layouts in the base/layoutsdirectory. That is, if a theme provides/themes/$theme_name/layouts/sidebar.htmland 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 viaconfig.tomlsettings.
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./packages: Various packages for shipping spec files like OpenAPI bindings and data definitions.
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.
-
Install the extended version (often the OS default) of Hugo: https://gohugo.io/getting-started/installing. Note that at least Hugo v0.123.1 is required.
Alternatively, use the Docker image at https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required to process the SCSS.)
-
Run
npm ito install the dependencies. Note that this will require NodeJS to be installed. -
Run
npm run get-proposalsto seed proposal data. This is merely for populating the content of the "Spec Change Proposals" page and is not required. -
Run
hugo serve(ordocker run --rm -it -v $(pwd):/src -p 1313:1313 klakegg/hugo:ext 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--disableFastRenderto the commandline. -
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 OpenAPI definitions, create a python3 virtualenv and activate it. Then run pip install -r ./scripts/requirements.txt
and finally python ./scripts/dump-openapi.py to generate it to ./scripts/openapi/api-docs.json. To make use of the generated file,
there are a number of options:
- You can open
./scripts/openapi-preview.htmlin your browser, and then open the file by clicking onLocal JSON File. - You can run a local HTTP server by running
./scripts/openapi-http-server.py, and then view the documentation by opening./scripts/openapi-preview.htmlin your browser.
Issue tracking
Specification issues are tracked on github at https://github.com/matrix-org/matrix-spec/issues.
See meta/github-labels.rst for information on what the labels mean.