|
|
|
@ -13,7 +13,7 @@ All changes to Specification content require a formal proposal process. This
|
|
|
|
|
involves writing a proposal, having it reviewed by the Matrix community, having
|
|
|
|
|
the proposal being accepted, then actually having your ideas implemented as
|
|
|
|
|
committed changes to the `Specification repository
|
|
|
|
|
<https://github.com/Matrix-org/Matrix-doc>`_.
|
|
|
|
|
<https://github.com/matrix-org/matrix-doc>`_.
|
|
|
|
|
|
|
|
|
|
The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as
|
|
|
|
|
follows:
|
|
|
|
@ -27,22 +27,22 @@ follows:
|
|
|
|
|
author desires; there is no formal template; the intention is to iterate
|
|
|
|
|
as quickly as possible to get to a good design.
|
|
|
|
|
- However, a `template with suggested headers
|
|
|
|
|
<https://github.com/Matrix-org/Matrix-doc/blob/master/proposals/proposals_template.md>`_
|
|
|
|
|
<https://github.com/matrix-org/matrix-doc/blob/master/proposals/proposals_template.md>`_
|
|
|
|
|
is available to get you started if necessary.
|
|
|
|
|
- Take care in creating your proposal. Specify your intended changes, and
|
|
|
|
|
give reasoning to back them up. Changes without justification will likely
|
|
|
|
|
be poorly received by the community.
|
|
|
|
|
|
|
|
|
|
- Fork and make a PR to the `Matrix-doc
|
|
|
|
|
<https://github.com/Matrix-org/Matrix-doc>`_ repository.
|
|
|
|
|
- Fork and make a PR to the `matrix-doc
|
|
|
|
|
<https://github.com/matrix-org/matrix-doc>`_ repository.
|
|
|
|
|
|
|
|
|
|
- Your proposal must live in the ``proposals/`` directory with a filename
|
|
|
|
|
that follows the format ``1234-my-new-proposal.md`` where 1234 is the MSC
|
|
|
|
|
ID.
|
|
|
|
|
- Your PR description must include a link to the rendered markdown document
|
|
|
|
|
and a summary of the proposal.
|
|
|
|
|
- It is often very helpful to link any related MSCs or `Matrix-doc issues
|
|
|
|
|
<https://github.com/Matrix-org/Matrix-doc/issues>`_ to give context
|
|
|
|
|
- It is often very helpful to link any related MSCs or `matrix-doc issues
|
|
|
|
|
<https://github.com/matrix-org/matrix-doc/issues>`_ to give context
|
|
|
|
|
for your proposal.
|
|
|
|
|
|
|
|
|
|
- Gather feedback as widely as possible from the community and core team.
|
|
|
|
@ -51,14 +51,14 @@ follows:
|
|
|
|
|
trade-offs are required to meet this goal. Decisions should be made to the
|
|
|
|
|
benefit of all major use cases.
|
|
|
|
|
- A good place to ask for feedback on a specific proposal is
|
|
|
|
|
`#Matrix-spec:Matrix.org <https://Matrix.to/#/#Matrix-spec:Matrix.org>`_.
|
|
|
|
|
However, it is welcome to use an alternative room if preferred please
|
|
|
|
|
advertise it in #Matrix-spec:Matrix.org and link to it on the PR for
|
|
|
|
|
visibility.
|
|
|
|
|
- For additional discussion areas, know that that #Matrix-dev:Matrix.org is
|
|
|
|
|
for developers using existing Matrix APIs, #Matrix:Matrix.org is for users
|
|
|
|
|
`#matrix-spec:matrix.org <https://matrix.to/#/#matrix-spec:matrix.org>`_.
|
|
|
|
|
If preferred, an alternative room can be created and advertised in
|
|
|
|
|
#matrix-spec:matrix.org. Please also link to the room in your PR
|
|
|
|
|
description.
|
|
|
|
|
- For additional discussion areas, know that that #matrix-dev:matrix.org is
|
|
|
|
|
for developers using existing Matrix APIs, #matrix:matrix.org is for users
|
|
|
|
|
trying to run Matrix apps (clients & servers) and
|
|
|
|
|
#Matrix-architecture:Matrix.org is for cross-cutting discussion of Matrix's
|
|
|
|
|
#matrix-architecture:matrix.org is for cross-cutting discussion of matrix's
|
|
|
|
|
architectural design.
|
|
|
|
|
- The point of the spec proposal process is to be collaborative rather than
|
|
|
|
|
competitive, and to try to solve the problem in question with the optimal
|
|
|
|
@ -94,7 +94,7 @@ follows:
|
|
|
|
|
during this process will warrant another MSC.
|
|
|
|
|
|
|
|
|
|
- Please sign off the spec PR as per the `CONTRIBUTING.rst
|
|
|
|
|
<https://github.com/Matrix-org/Matrix-doc/blob/master/CONTRIBUTING.rst>`_
|
|
|
|
|
<https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst>`_
|
|
|
|
|
guidelines.
|
|
|
|
|
|
|
|
|
|
- Your PR will then be reviewed and hopefully merged on the grounds it is
|
|
|
|
@ -148,8 +148,8 @@ possible.
|
|
|
|
|
|
|
|
|
|
The process for handling proposals is described in the following diagram. Note
|
|
|
|
|
that the lifetime of a proposal is tracked through the corresponding labels for
|
|
|
|
|
each stage in the `Matrix-doc issue tracker
|
|
|
|
|
<https://github.com/Matrix-org/Matrix-doc/issues>`_.
|
|
|
|
|
each stage in the `matrix-doc issue tracker
|
|
|
|
|
<https://github.com/matrix-org/matrix-doc/issues>`_.
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
|
@ -220,18 +220,19 @@ Proposal Tracking
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
This is a living document generated from the list of proposals at
|
|
|
|
|
`Matrix-doc/issues <https://github.com/Matrix-org/Matrix-doc/issues>`_ on
|
|
|
|
|
`matrix-doc/issues <https://github.com/matrix-org/matrix-doc/issues>`_ on
|
|
|
|
|
GitHub.
|
|
|
|
|
|
|
|
|
|
We use labels and some metadata in MSC PR descriptions to generate this page.
|
|
|
|
|
Labels are assigned by the core team whilst triaging the issues based on those
|
|
|
|
|
which exist in the Matrix-doc repo already.
|
|
|
|
|
which exist in the `matrix-doc <https://github.com/matrix-org/matrix-doc>`_
|
|
|
|
|
repo already.
|
|
|
|
|
|
|
|
|
|
It is worth mentioning that a previous version of the MSC process used a
|
|
|
|
|
mixture of GitHub issues and PRs, leading to some MSC numbers deriving from
|
|
|
|
|
GitHub issue IDs instead. A useful feature of GitHub is that it does
|
|
|
|
|
automatically resolve to an issue, if an issue ID is placed in a pull URL. This
|
|
|
|
|
means that https://github.com/Matrix-org/Matrix-doc/pull/$MSCID will correctly
|
|
|
|
|
means that https://github.com/matrix-org/matrix-doc/pull/$MSCID will correctly
|
|
|
|
|
resolve to the desired MSC, whether it started as an issue or a PR.
|
|
|
|
|
|
|
|
|
|
Other metadata:
|
|
|
|
|