wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #2050 from matrix-org/travis/1.0/clarify-proposals

Browse source 
Synchronize proposals_intro.rst and CONTRIBUTING.rst
This commit is contained in:
Travis Ralston 2019-05-29 18:26:53 -06:00 • committed by GitHub
commit 41a036a453
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 32 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

28
CONTRIBUTING.rst
View file

@ -26,10 +26,11 @@ For this to be effective, the APIs need to be present and working correctly in a
server before they can be documented in the specification. This process can take server before they can be documented in the specification. This process can take
some time to complete. some time to complete.
For this reason, we have not found the github pull-request model effective for Changes to the protocol (new endpoints, ideas, etc) need to go through the
discussing changes to the specification. Instead, we have adopted the workflow `proposals process <https://matrix.org/docs/spec/proposals>`_. Other changes,
as described at https://matrix.org/docs/spec/proposals - *please read this for such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal.
details on how to contribute spec changes*. If you're not sure, visit us at `#matrix-spec:matrix.org`_
and ask.
Other changes Other changes
@ -51,8 +52,7 @@ following:
<https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label. <https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label.
(If there is any doubt about whether it is the spec or the implementations (If there is any doubt about whether it is the spec or the implementations
that need fixing, please discuss it with us first in `#matrix-dev:matrix.org that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.)
<http://matrix.to/#/#matrix-dev:matrix.org>`_.)
* Clarifications to the specification which do not change the behaviour of * Clarifications to the specification which do not change the behaviour of
Matrix servers or clients in a way which might introduce compatibility Matrix servers or clients in a way which might introduce compatibility
@ -60,14 +60,16 @@ following:
`clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_ `clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
label. label.
For example, recommendations for UI behaviour do not require a proposal For example, areas where the specification is unclear do not require a proposal
document. On the other hand, changes to event contents would be best to fix. On the other hand, introducing new behaviour is best represented by a
discussed in a proposal document even though no changes would be necessary to proposal.
server implementations.
For such changes, please do just open a `pull request`_. For such changes, please do just open a `pull request`_. If you're not sure if
your change is covered by the above, please visit `#matrix-spec:matrix.org` and
ask.
.. _pull request: https://help.github.com/articles/about-pull-requests .. _`pull request`: https://help.github.com/articles/about-pull-requests
.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org
Adding to the changelog Adding to the changelog
@ -96,7 +98,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
* ``breaking`` - Used when the change is not backwards compatible. * ``breaking`` - Used when the change is not backwards compatible.
* ``deprecation`` - Used when deprecating something * ``deprecation`` - Used when deprecating something.
All news fragments must have a brief summary explaining the change in the All news fragments must have a brief summary explaining the change in the
contents of the file. The summary must end in a full stop to be in line with contents of the file. The summary must end in a full stop to be in line with

26
specification/proposals_intro.rst
View file

@ -13,12 +13,18 @@ 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.
All changes to Specification content require a formal proposal process. This Most changes to the Specification require a formal proposal. Bug fixes, typos,
involves writing a proposal, having it reviewed by everyone, having the and clarifications to existing behaviour do not need proposals - see the
proposal being accepted, then actually having your ideas implemented as `contributing guide <https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst>`_
committed changes to the `Specification repository for more information on what does and does not need a proposal.
The proposal process involves some technical writing, having it reviewed by
everyone, 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>`_.
.. TODO: Replace GH team link with https://matrix.org/foundation or something
Meet the `members of the Core Team Meet the `members of the Core Team
<https://github.com/orgs/matrix-org/teams/spec-core-team/members>`_, a group of <https://github.com/orgs/matrix-org/teams/spec-core-team/members>`_, a group of
individuals tasked with ensuring the spec process is as smooth and painless as individuals tasked with ensuring the spec process is as smooth and painless as
@ -33,14 +39,15 @@ Guiding Principles
Proposals **must** act to the greater benefit of the entire Matrix ecosystem, Proposals **must** act to the greater benefit of the entire Matrix ecosystem,
rather than benefiting or privileging any single player or subset of players - rather than benefiting or privileging any single player or subset of players -
and must not contain any patent encumbered intellectual property. Members of the Core Team pledge to act as and must not contain any patent encumbered intellectual property. Members of
a neutral custodian for Matrix on behalf of the whole ecosystem. the Core Team pledge to act as a neutral custodian for Matrix on behalf of the
whole ecosystem.
For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That
includes client users, server admins, client developers, bot developers, includes client users, server admins, client developers, bot developers,
bridge and application service developers, users and admins who are indirectly using Matrix via bridge and application service developers, users and admins who are indirectly
3rd party networks which happen to be bridged, server developers, room using Matrix via 3rd party networks which happen to be bridged, server developers,
moderators and admins, companies/projects building products or services on room moderators and admins, companies/projects building products or services on
Matrix, spec contributors, translators, and those who created it in Matrix, spec contributors, translators, and those who created it in
the first place. the first place.
@ -242,6 +249,7 @@ Spec PR Merged merged A proposal with
Postponed proposal-postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps Postponed proposal-postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps
sometime in the future sometime in the future
Closed proposal-closed A proposal which has been reviewed and deemed unsuitable for acceptance Closed proposal-closed A proposal which has been reviewed and deemed unsuitable for acceptance
Obsolete obsolete A proposal which has been made obsolete by another proposal or decision elsewhere.
=============================== ============================= ==================================== =============================== ============================= ====================================