Notes on issue categorisation

pull/1023/head
Richard van der Hoff 7 years ago
parent 4ed19ef8be
commit d3a4ad06c7

@ -1,9 +1,95 @@
This repository contains the documentation for Matrix.
Structure
=========
Primarily, that means the Matrix protocol specifcation, but this repo also
comtains a lot of supporting documents, including some introductions to Matrix,
and, notably, a list of projects using Matrix which is visible on the
`matrix.org website <https://matrix.org/docs/projects/try-matrix-now.html>`_.
- ``api`` : Contains the HTTP API specification.
Issue tracking
==============
Issues with the Matrix specification and supporting documentation are tracked
in `GitHub <https://github.com/matrix-org/matrix-doc/issues>`_.
The following labels are used to help categorize issues:
`spec-omission <https://github.com/matrix-org/matrix-doc/labels/spec-omission>`_
Things which have been implemented but not currently specified. These may
range from entire API endpoints, to particular options or return
parameters.
Issues with this label will have been implemented in `Synapse
<https://github.com/matrix-org/synapse>`_. Normally there will be a design
document in Google Docs or similar which describes the feature.
Examples:
* `Spec PUT /directory/list <https://github.com/matrix-org/matrix-doc/issues/417>`_
* `Unspec'd server_name request param for /join/{roomIdOrAlias}
<https://github.com/matrix-org/matrix-doc/issues/904>`_
`clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
An area where the spec could do with being more explicit.
Examples:
* `Spec the implicit limit on /syncs
<https://github.com/matrix-org/matrix-doc/issues/708>`_
* `Clarify the meaning of the currently_active flags in presence events
<https://github.com/matrix-org/matrix-doc/issues/686>`_
`bug <https://github.com/matrix-org/matrix-doc/labels/bug>`_
Something which is in the spec, but is wrong.
Note: this is *not* for things that are badly designed or don't work well
(for which see 'improvement' or 'feature') - it is for places where the
spec doesn't match reality.
Examples:
* `swagger is wrong for directory PUT
<https://github.com/matrix-org/matrix-doc/issues/933>`_
* `receipts section still refers to initialSync
<https://github.com/matrix-org/matrix-doc/issues/695>`_
`improvement <https://github.com/matrix-org/matrix-doc/labels/improvement>`_
A suggestion for a relaatively simple improvement to the protocol.
Examples:
* `We need a 'remove 3PID' API so that users can remove mappings
<https://github.com/matrix-org/matrix-doc/issues/620>`_
* `We should mandate that /publicRooms requires an access_token
<https://github.com/matrix-org/matrix-doc/issues/612>`_
`feature <https://github.com/matrix-org/matrix-doc/labels/feature>`_
A suggestion for a significant extension to the matrix protocol which
needs considerable consideration before implementation.
Examples:
* `Peer-to-peer Matrix <https://github.com/matrix-org/matrix-doc/issues/710>`_
* `Specify a means for clients to "edit" previous messages
<https://github.com/matrix-org/matrix-doc/issues/682>`_
`projects <https://github.com/matrix-org/matrix-doc/labels/projects>`_
A project which needs adding to the 'Try Matrix Now' page.
Examples:
* `add https://gitlab.com/uhoreg/matrix-appservice-prosody
<https://github.com/matrix-org/matrix-doc/issues/1016>`_
* `add https://github.com/tavoda/matrix-java project
<https://github.com/matrix-org/matrix-doc/issues/956>`_
Structure of this repository
============================
- ``api`` : Contains the HTTP API specification, documented using OpenAPI
(swagger).
- ``attic``: Contains historical sections of specification for reference
purposes.
- ``changelogs``: Contains change logs for the various parts of the

Loading…
Cancel
Save