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

Synchronize proposals_intro.rst and CONTRIBUTING.rst

CONTRIBUTING.rst

@@ -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
 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
@@ -51,8 +52,7 @@ following:
   <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
-  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
   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>`_
   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
@@ -96,7 +98,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 * ``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
 contents of the file. The summary must end in a full stop to be in line with

specification/proposals_intro.rst

@@ -13,12 +13,18 @@ Proposals for Spec Changes to Matrix
 If you are interested in submitting a change to the Matrix Specification,
 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>`_.
 
+.. TODO: Replace GH team link with https://matrix.org/foundation or something
+
 Meet the `members of the Core Team
 <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
@@ -33,14 +39,15 @@ Guiding Principles
 
 Proposals **must** act to the greater benefit of the entire Matrix ecosystem,
 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
 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
 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
                                                                 sometime in the future
 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.
 ===============================  =============================  ====================================