Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-06 11:44:10 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Fix capatilization

Browse source
This commit is contained in:
Andrew Morgan 2018-10-15 15:48:55 +02:00
parent d2e827e0c6
commit 80d1d4af9c
1 changed files with 32 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
specification/proposals_intro.rst
View file

@ -6,19 +6,19 @@
Proposals for Spec Changes to Matrix Proposals for Spec Changes to Matrix
------------------------------------ ------------------------------------
If you are interested in submitting a change to the matrix specification, If you are interested in submitting a change to the Matrix Specification,
please take note of the following guidelines. please take note of the following guidelines.
Community changes to the specification require a formal proposal process. This Community changes to the Specification require a formal proposal process. This
involves writing a proposal, having it reviewed by the matrix community, having involves writing a proposal, having it reviewed by the Matrix community, having
the proposal being accepted, then actually having your ideas implemented as the proposal being accepted, then actually having your ideas implemented as
committed changes to the `specification repository 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 The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as
follows: follows:
- Create a first-draft of your proposal using `github-flavored markdown - Create a first-draft of your proposal using `GitHub-flavored markdown
<https://help.github.com/articles/basic-writing-and-formatting-syntax/>`_ <https://help.github.com/articles/basic-writing-and-formatting-syntax/>`_
- In the document, clearly state the problem being solved, and the possible - In the document, clearly state the problem being solved, and the possible
@ -27,19 +27,19 @@ follows:
author desires; there is no formal template; the intention is to iterate author desires; there is no formal template; the intention is to iterate
as quickly as possible to get to a good design. as quickly as possible to get to a good design.
- However, a `template with suggested headers - 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. is available to get you started if necessary.
- Take care in creating your proposal. Specify your intended changes, and - Take care in creating your proposal. Specify your intended changes, and
give reasoning to back them up. Changes without justification will likely give reasoning to back them up. Changes without justification will likely
be poorly received by the community. be poorly received by the community.
- Fork and make a PR to the `matrix-doc - Fork and make a PR to the `Matrix-doc
<https://github.com/matrix-org/matrix-doc>`_ repository. <https://github.com/Matrix-org/Matrix-doc>`_ repository.
- Your PR description must include a link to the rendered markdown document - Your PR description must include a link to the rendered markdown document
and a summary of the proposal. and a summary of the proposal.
- It is often very helpful to link any related MSCs or `matrix-doc issues - 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 <https://github.com/Matrix-org/Matrix-doc/issues>`_ to give context
for your proposal. for your proposal.
- Gather feedback as widely as possible from the community and core team. - Gather feedback as widely as possible from the community and core team.
@ -48,14 +48,14 @@ follows:
trade-offs are required to meet this goal. Decisions should be made to the trade-offs are required to meet this goal. Decisions should be made to the
benefit of all major use cases. benefit of all major use cases.
- A good place to ask for feedback on a specific proposal is - A good place to ask for feedback on a specific proposal is
`#matrix-spec:matrix.org <https://matrix.to/#/#matrix-spec:matrix.org>`_. `#Matrix-spec:Matrix.org <https://Matrix.to/#/#Matrix-spec:Matrix.org>`_.
However, it is welcome to use an alternative room if preferred please 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 advertise it in #Matrix-spec:Matrix.org and link to it on the PR for
visibility. visibility.
- For additional discussion areas, know that that #matrix-dev:matrix.org is - For additional discussion areas, know that that #Matrix-dev:Matrix.org is
for developers using existing Matrix APIs, #matrix:matrix.org is for users for developers using existing Matrix APIs, #Matrix:Matrix.org is for users
trying to run matrix apps (clients & servers) and 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. architectural design.
- The point of the spec proposal process is to be collaborative rather than - 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 competitive, and to try to solve the problem in question with the optimal
@ -68,7 +68,7 @@ follows:
acceptance. acceptance.
- Members of the core team and community will review and discuss the PR in the - Members of the core team and community will review and discuss the PR in the
comments and in relevant rooms on matrix. Discussion outside of Github should comments and in relevant rooms on Matrix. Discussion outside of GitHub should
be summarised in a comment on the PR. be summarised in a comment on the PR.
- At some point a member of the core team will propose a motion for a final - At some point a member of the core team will propose a motion for a final
comment period (FCP) with a *disposition* of merge, close or postpone. This comment period (FCP) with a *disposition* of merge, close or postpone. This
@ -84,19 +84,19 @@ follows:
conclude is raised, the FCP can be cancelled and the MSC will continue to conclude is raised, the FCP can be cancelled and the MSC will continue to
evolve accordingly. evolve accordingly.
- Once your proposal has been accepted and merged, it is time to submit the - Once your proposal has been accepted and merged, it is time to submit the
actual change to the specification that your proposal reasoned about. This is actual change to the Specification that your proposal reasoned about. This is
known as a spec PR. However in order for your spec PR to be accepted, you known as a spec PR. However in order for your spec PR to be accepted, you
**must** show an implementation to prove that it works well in practice. In **must** show an implementation to prove that it works well in practice. In
addition, any significant unforeseen changes to the original idea found addition, any significant unforeseen changes to the original idea found
during this process will warrant another MSC. during this process will warrant another MSC.
- Please sign off the spec PR as per the `CONTRIBUTING.rst - 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. guidelines.
- Your PR will then be reviewed and hopefully merged on the grounds it is - Your PR will then be reviewed and hopefully merged on the grounds it is
implemented sufficiently. If so, then give yourself a pat on the back knowing implemented sufficiently. If so, then give yourself a pat on the back knowing
you've contributed to the matrix protocol for the benefit of users and you've contributed to the Matrix protocol for the benefit of users and
developers alike :) developers alike :)
Proposals **must** act to the greater benefit of the entire Matrix ecosystem, Proposals **must** act to the greater benefit of the entire Matrix ecosystem,
@ -145,8 +145,8 @@ possible.
The process for handling proposals is described in the following diagram. Note 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 that the lifetime of a proposal is tracked through the corresponding labels for
each stage in the `matrix-doc issue tracker each stage in the `Matrix-doc issue tracker
<https://github.com/matrix-org/matrix-doc/issues>`_. <https://github.com/Matrix-org/Matrix-doc/issues>`_.
:: ::
@ -217,33 +217,33 @@ Proposal Tracking
----------------- -----------------
This is a living document generated from the list of proposals at 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. GitHub.
We use labels and some metadata in MSC PR descriptions to generate this page. 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 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 repo already.
It is worth mentioning that a previous version of the MSC process used a 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 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 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 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. resolve to the desired MSC, whether it started as an issue or a PR.
Other metadata: Other metadata:
- The MSC (Matrix Spec Change) number is taken from the github Pull Request ID. - The MSC (Matrix Spec Change) number is taken from the GitHub Pull Request ID.
This is carried for the lifetime of the proposal. These IDs do not necessary This is carried for the lifetime of the proposal. These IDs do not necessary
represent a chronological order. represent a chronological order.
- The github PR title will act as the MSC's title. - The GitHub PR title will act as the MSC's title.
- Please link to the spec PR (if any) by adding a "PRs: #1234" line in the - Please link to the spec PR (if any) by adding a "PRs: #1234" line in the
issue description. issue description.
- The creation date is taken from the github PR, but can be overridden by - The creation date is taken from the GitHub PR, but can be overridden by
adding a "Date: yyyy-mm-dd" line in the PR description. adding a "Date: yyyy-mm-dd" line in the PR description.
- Updated Date is taken from github. - Updated Date is taken from GitHub.
- Author is the creator of the MSC PR, but can be overridden by adding a - Author is the creator of the MSC PR, but can be overridden by adding a
"Author: @username" line in the body of the issue description. Please make "Author: @username" line in the body of the issue description. Please make
sure @username is a github user (include the @!) sure @username is a GitHub user (include the @!)
- A shepherd can be assigned by adding a "Shepherd: @username" line in the - A shepherd can be assigned by adding a "Shepherd: @username" line in the
issue description. Again, make sure this is a real Github user. issue description. Again, make sure this is a real GitHub user.