diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6f17afe6..2a7416b1 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -21,44 +21,15 @@ Matrix-doc workflows Specification changes ~~~~~~~~~~~~~~~~~~~~~ -The Matrix specification documents the APIs which Matrix clients can use. 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. +The Matrix specification documents the APIs which Matrix clients and servers use. +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 -discussing changes to the specification. Instead, we have adopted the following -workflow: - -1. Create a discussion document outlining the proposed change. The document - should include details such as the HTTP endpoint being changed (or the - suggested URL for a new endpoint), any new or changed parameters and response - fields, and generally as much detail about edge-cases and error handling as - is practical at this stage. - - The Matrix Core Team's preferred tool for such discussion documents is - `Google Docs `_ thanks to its support for comment - threads. Works in progress are kept in the `Matrix Design drafts folder - `_. - -2. Seek feedback on the proposal. `#matrix-dev:matrix.org - `_ is a good place to reach the - core team and others who may be interested in your proposal. - -3. Implement the changes in servers and clients. Refer to the CONTRIBUTING files - of the relevant projects for details of how best to do this. - - In general we will be unable to publish specification updates until the - reference server implements them, and they have been proven by a working - client implementation. - -4. Iterate steps 1-3 as necessary. - -5. Write the specification for the change, and create a `pull request`_ for - it. It may be that much of the text of the change can be taken directly from - the discussion document, though typically some effort will be needed to - change to the ReST syntax and to ensure that the text is as clear as - possible. +discussing changes to the specification. Instead, we have adopted the workflow +as described at https://matrix.org/docs/spec/proposals - *please read this for +details on how to contribute spec changes*. Other changes diff --git a/scripts/proposals.py b/scripts/proposals.py new file mode 100644 index 00000000..8b2107ac --- /dev/null +++ b/scripts/proposals.py @@ -0,0 +1,157 @@ +# proposals.py: generate an RST file (proposals.rst) from queries to github.com/matrix.org/matrix-doc/issues. +# v0.0.1 + +import requests +import re +from datetime import datetime +from m2r import convert as m2r + +pagecount = 1 +authors = set() +prs = set() + +def getpage(url, page): + resp = requests.get(url + str(page)) + + for link in resp.links.values(): + if link['rel'] == 'last': + pagecount = re.search('page=(.+?)', link['url']).group(1) + + return resp.json() + +def getbylabel(label): + pagecount = 1 + json = list() + urlbase = 'https://api.github.com/repos/matrix-org/matrix-doc/issues?state=open&labels=' + label + '&page=' + print(urlbase) + json.extend(getpage(urlbase, 1)) + for page in range(2, int(pagecount) + 1): + getpage(urlbase, page) + + return json + +# new status labels: +labels = ['proposal-wip', 'proposal-ready-for-review', + 'proposal-in-review', 'proposal-passed-review', 'spec-pr-missing', + 'spec-pr-ready-for-review', 'spec-pr-in-review', 'merged', 'abandoned', 'rejected', 'blocked', 'obsolete' ] +#labels = ['p1', 'p2', 'p3', 'p4', 'p5'] +issues = {} + +for label in labels: + issues[label] = getbylabel(label) + +text_file = open("../specification/proposals.rst", "w") + +text_file.write("Tables of Tracked Proposals\n---------------------------\n\n") + + +for label in labels: + if (len(issues[label]) == 0): + continue + + text_file.write(label + "\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n") + text_file.write(".. list-table::\n :header-rows: 1\n :widths: auto\n :stub-columns: 1\n\n") + text_file.write(" * - MSC\n") + text_file.write(" - Proposal Title\n") + text_file.write(" - Creation Date\n") + text_file.write(" - Update Date\n") + text_file.write(" - Documenation\n") + text_file.write(" - Author\n") + text_file.write(" - Shepherd\n") + text_file.write(" - PRs\n") + + for item in issues[label]: + # set the created date, find local field, otherwise Github + print(item) + body = str(item['body']) + created = re.search('^Date: (.+?)\n', body, flags=re.MULTILINE) + if created is not None: + created = created.group(1).strip() + try: + created = datetime.strptime(created, "%d/%m/%Y") + created = created.strftime('%Y-%m-%d') + except: + pass + try: + created = datetime.strptime(created, "%Y-%m-%d") + created = created.strftime('%Y-%m-%d') + except: + pass + else : + created = datetime.strptime(item['created_at'], "%Y-%m-%dT%XZ") + created = created.strftime('%Y-%m-%d') + item['created'] = created + + issues_to_print = list(issues[label]) + issues_to_print.sort(key=lambda issue_sort: issue_sort["created"]) + + for item in issues_to_print: + # MSC number + text_file.write(" * - `MSC" + str(item['number']) + " <" + item['html_url'] + ">`_\n") + + # title from Github issue + text_file.write(" - " + item['title'] + "\n") + + # created date + text_file.write(" - " + item['created'] + "\n") + + # last updated, purely Github + updated = datetime.strptime(item['updated_at'], "%Y-%m-%dT%XZ") + text_file.write(" - " + updated.strftime('%Y-%m-%d') + "\n") + + # list of document links (urls comma-separated) + maindoc = re.search('^Documentation: (.+?)\n', str(item['body'])) + if maindoc is not None: + maindoc = maindoc.group(1) + doc_list_formatted = ["`" + str(item['number']) + "-" + str(i) + " <" + x.strip() + ">`_" for i, x in enumerate(maindoc.split(','),1)] + text_file.write(" - " + ', '.join(doc_list_formatted)) + else: + text_file.write(" - ") + text_file.write("\n") + + # author list, if missing just use Github issue creator + author = re.search('^Author: (.+?)$', str(item['body']), flags=re.MULTILINE) + if author is not None: + author_list_formatted = set() + author_list = author.group(1) + for a in author_list.split(","): + authors.add(a.strip()) + author_list_formatted.add("`" + str(a.strip()) + "`_") + text_file.write(" - " + ', '.join(author_list_formatted)) + else: + author = "@" + item['user']['login'] + authors.add(author) + text_file.write(" - `" + str(author) + "`_") + text_file.write("\n") + + # shepherd (currently only one) + shepherd = re.search('Shepherd: (.+?)\n', str(item['body'])) + if shepherd is not None: + authors.add(shepherd.group(1).strip()) + shepherd = "`" + shepherd.group(1).strip() + "`_" + text_file.write(" - " + str(shepherd) + "\n") + + # PRs + pr_list = re.search('PRs: (.+?)$', str(item['body'])) + if pr_list is not None: + pr_list_formatted = set() + pr_list = pr_list.group(1) + for p in pr_list.split(","): + prs.add(p.strip()) + pr_list_formatted.add("`PR" + str(p.strip()) + "`_") + text_file.write(" - " + ', '.join(pr_list_formatted)) + text_file.write("\n") + else: + text_file.write(" - \n") + + text_file.write("\n\n\n") + +text_file.write("\n") + +for author in authors: + text_file.write("\n.. _" + author + ": https://github.com/" + author[1:]) + +for pr in prs: + text_file.write("\n.. _PR" + pr + ": https://github.com/matrix-org/matrix-doc/pull/" + pr.replace('#', '')) + +text_file.close() diff --git a/specification/intro.rst b/specification/intro.rst index 064f9d17..ad545248 100644 --- a/specification/intro.rst +++ b/specification/intro.rst @@ -96,6 +96,13 @@ instant messages, VoIP call setups, or any other objects that need to be reliably and persistently pushed from A to B in an interoperable and federated manner. + +Spec Change Proposals +~~~~~~~~~~~~~~~~~~~~~ +To propose a change to the Matrix Spec, see the explanations at `Proposals +for Spec Changes to Matrix `_. + + Architecture ------------ diff --git a/specification/proposals.rst b/specification/proposals.rst new file mode 100644 index 00000000..da9d277f --- /dev/null +++ b/specification/proposals.rst @@ -0,0 +1,615 @@ +Tables of Tracked Proposals +--------------------------- + +proposal-wip +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documenation + - Author + - Shepherd + - PRs + * - `MSC455 `_ + - Do we want to specify a matrix:// URI scheme for rooms? (SPEC-5) + - 2014-09-15 + - 2018-05-15 + - `455-1 `_ + - `@KitsuneRal`_ + - None + - + * - `MSC586 `_ + - Federation API for canonicalising MXIDs + - 2014-10-27 + - 2018-05-15 + - `586-1 `_ + - `@ara4n`_ + - None + - + * - `MSC489 `_ + - Extensible Profiles. (SPEC-93) + - 2015-01-19 + - 2018-05-15 + - `489-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1196 `_ + - Matrix Escape Hatch (Versioned Rooms) + - 2015-10-22 + - 2018-05-15 + - `1196-1 `_ + - `@leonerd`_ + - None + - + * - `MSC1238 `_ + - Push to Talk + - 2016-04-13 + - 2018-05-15 + - `1238-1 `_ + - `@aviraldg`_ + - None + - `PR#310`_ + * - `MSC1198 `_ + - Threading API + - 2016-05-23 + - 2018-05-15 + - `1198-1 `_ + - `@Half-Shot`_ + - None + - + * - `MSC1207 `_ + - Publishing Room Lists for 3rd party networks + - 2016-10-21 + - 2018-05-15 + - `1207-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC441 `_ + - Support for Reactions / Aggregations + - 2016-12-25 + - 2018-05-15 + - `441-1 `_ + - `@pik`_ + - `@ara4n`_ + - + * - `MSC1237 `_ + - Improving m.location with GeoJSON and accuracy + - 2017-05-19 + - 2018-05-15 + - `1237-1 `_ + - `@Half-Shot`_ + - None + - `PR#919`_ + * - `MSC971 `_ + - Add groups stuff to spec + - 2017-08-10 + - 2018-05-15 + - `971-1 `_, `971-2 `_, `971-3 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1215 `_ + - Groups as Rooms + - 2017-10-17 + - 2018-05-15 + - `1215-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1217 `_ + - Visibility of groups to group members and their non-members + - 2017-10-30 + - 2018-05-15 + - `1217-1 `_ + - `@lampholder`_ + - None + - + * - `MSC1218 `_ + - Bridging group membership with 3rd party group sources + - 2017-11-15 + - 2018-05-15 + - `1218-1 `_ + - `@lukebarnard1`_ + - None + - + * - `MSC1219 `_ + - Proposal for storing megolm keys serverside + - 2017-11-23 + - 2018-05-15 + - `1219-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1221 `_ + - Improving Presence + - 2017-12-26 + - 2018-05-15 + - `1221-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1222 `_ + - Pushing updates about Groups (Communities) to clients + - 2018-01-02 + - 2018-05-15 + - `1222-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1225 `_ + - Extensible event types & fallback in Matrix + - 2018-02-18 + - 2018-05-15 + - `1225-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1227 `_ + - Proposal for lazy-loading room members to improve initial sync speed and client RAM usage + - 2018-03-05 + - 2018-05-15 + - `1227-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1206 `_ + - Proposal for improved bot support + - 2018-03-14 + - 2018-05-15 + - `1206-1 `_ + - `@turt2live`_ + - None + - + * - `MSC1228 `_ + - Removing MXIDs from events + - 2018-04-19 + - 2018-05-15 + - `1228-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1231 `_ + - Handling Consent for Privacy Policy + - 2018-05-02 + - 2018-05-15 + - `1231-1 `_ + - `@neilisfragile`_ + - None + - + + + +proposal-ready-for-review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documenation + - Author + - Shepherd + - PRs + * - `MSC1183 `_ + - Document key-share requests + - 2018-04-30 + - 2018-05-15 + - `1183-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1232 `_ + - Media limits API + - 2018-05-04 + - 2018-05-15 + - `1232-1 `_ + - `@Half-Shot`_ + - None + - `PR#1189`_ + + + +proposal-in-review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documenation + - Author + - Shepherd + - PRs + * - `MSC433 `_ + - Support for discovering API endpoints via .well-known URIs (SPEC-121) + - 2015-03-08 + - 2018-05-15 + - `433-1 `_, `433-2 `_ + - `@maxidor`_, `others`_ + - `@uhoreg`_ + - + * - `MSC1194 `_ + - A way for HSes to remove bindings from ISes + - 2018-05-09 + - 2018-05-15 + - `1194-1 `_ + - `@dbkr`_ + - None + - + + + +proposal-passed-review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documenation + - Author + - Shepherd + - PRs + * - `MSC1226 `_ + - State Reset mitigation proposal + - 2018-02-20 + - 2018-05-15 + - `1226-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1229 `_ + - Mitigating abuse of the event depth parameter over federation + - 2018-04-30 + - 2018-05-15 + - `1229-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1233 `_ + - A proposal for organising spec proposals + - 2018-05-10 + - 2018-05-15 + - `1233-1 `_ + - `@ara4n`_ + - None + - `PR#1240`_ + * - `MSC1234 `_ + - Rich Replies format + - 2018-05-12 + - 2018-05-17 + - `1234-1 `_ + - `@t3chguy`_ + - None + - + * - `MSC1236 `_ + - Matrix Widget API v2 + - 2018-05-13 + - 2018-05-15 + - `1236-1 `_ + - `@rxl881`_ + - None + - + + + +spec-pr-missing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documenation + - Author + - Shepherd + - PRs + * - `MSC1197 `_ + - Ignoring Users + - 2016-05-03 + - 2018-05-15 + - `1197-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1201 `_ + - Device Management API + - 2016-07-14 + - 2018-05-15 + - `1201-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1203 `_ + - 3rd Party Entity lookup API + - 2016-07-21 + - 2018-05-15 + - `1203-1 `_ + - `@leonerd`_ + - None + - + * - `MSC1205 `_ + - Proposal for multi-device deletion API + - 2016-10-12 + - 2018-05-15 + - `1205-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1208 `_ + - Encrypted attachment format + - 2016-10-26 + - 2018-05-15 + - `1208-1 `_ + - `@NegativeMjark`_ + - None + - + * - `MSC739 `_ + - Reporting inappropriate content in Matrix + - 2016-11-21 + - 2018-05-15 + - `739-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1211 `_ + - Megolm session export format + - 2017-01-03 + - 2018-05-15 + - `1211-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1212 `_ + - Device List Update Stream + - 2017-01-18 + - 2018-05-15 + - `1212-1 `_ + - `@richvdh`_ + - None + - + * - `MSC829 `_ + - Need to spec msisdn login API + - 2017-03-08 + - 2018-05-15 + - `829-1 `_ + - `@dbkr`_ + - None + - + * - `MSC855 `_ + - spec m.login.msisdn UI auth type + - 2017-03-24 + - 2018-05-15 + - `855-1 `_ + - `@dbkr`_ + - None + - + * - `MSC910 `_ + - Add new Read Marker API to docs + - 2017-05-08 + - 2018-05-15 + - + - `@lukebarnard1`_ + - None + - + * - `MSC1067 `_ + - Spec @mentions + - 2017-07-14 + - 2018-05-15 + - `1067-1 `_ + - `@lukebarnard1`_ + - None + - + * - `MSC1214 `_ + - Related Groups (i.e. flair) + - 2017-10-03 + - 2018-05-15 + - `1214-1 `_ + - `@lukebarnard1`_ + - None + - + * - `MSC1216 `_ + - @room notification proposal + - 2017-10-23 + - 2018-05-15 + - `1216-1 `_ + - `@dbkr`_ + - None + - `PR#1176`_ + * - `MSC1230 `_ + - Temporary mitigation for depth parameter abuse + - 2018-05-01 + - 2018-05-15 + - `1230-1 `_ + - `@ara4n`_ + - None + - + * - `MSC1234 `_ + - Rich Replies format + - 2018-05-12 + - 2018-05-17 + - `1234-1 `_ + - `@t3chguy`_ + - None + - + + + +merged +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documenation + - Author + - Shepherd + - PRs + * - `MSC1199 `_ + - Notifications API + - 2016-05-23 + - 2018-05-15 + - `1199-1 `_ + - `@dbkr`_ + - None + - + * - `MSC1200 `_ + - Configuration of E2E encryption in a room + - 2016-06-16 + - 2018-05-15 + - `1200-1 `_ + - `@richvdh`_ + - None + - + * - `MSC1204 `_ + - Access Token Semantics (refresh and macaroons) - aka Auth Sept 2016 Edition + - 2016-09-29 + - 2018-05-15 + - `1204-1 `_ + - `@richvdh`_ + - None + - + + + +abandoned +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documenation + - Author + - Shepherd + - PRs + * - `MSC531 `_ + - Homeservers as OAuth authorization endpoints (resource owners) (SPEC-206) + - 2015-07-25 + - 2018-05-15 + - `531-1 `_ + - `@Kegsay`_ + - None + - + * - `MSC1202 `_ + - Profile Personae + - 2016-07-15 + - 2018-05-15 + - `1202-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1209 `_ + - Server Side Profile API + - 2016-11-01 + - 2018-05-15 + - `1209-1 `_ + - `@erikjohnston`_ + - None + - + * - `MSC1213 `_ + - Set defaults for m.federate + - 2018-05-10 + - 2018-05-15 + - `1213-1 `_ + - `@psaavedra`_ + - None + - + + + +obsolete +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: auto + :stub-columns: 1 + + * - MSC + - Proposal Title + - Creation Date + - Update Date + - Documenation + - Author + - Shepherd + - PRs + * - `MSC1235 `_ + - Proposal for Calendar Events + - 2018-02-06 + - 2018-05-15 + - `1235-1 `_ + - `@Half-Shot`_ + - None + - + + + + + +.. _@t3chguy: https://github.com/t3chguy +.. _@KitsuneRal: https://github.com/KitsuneRal +.. _@pik: https://github.com/pik +.. _@leonerd: https://github.com/leonerd +.. _@turt2live: https://github.com/turt2live +.. _@erikjohnston: https://github.com/erikjohnston +.. _@neilisfragile: https://github.com/neilisfragile +.. _@psaavedra: https://github.com/psaavedra +.. _@richvdh: https://github.com/richvdh +.. _@NegativeMjark: https://github.com/NegativeMjark +.. _@ara4n: https://github.com/ara4n +.. _@lukebarnard1: https://github.com/lukebarnard1 +.. _@lampholder: https://github.com/lampholder +.. _@dbkr: https://github.com/dbkr +.. _@maxidor: https://github.com/maxidor +.. _others: https://github.com/thers +.. _@rxl881: https://github.com/rxl881 +.. _@uhoreg: https://github.com/uhoreg +.. _@Kegsay: https://github.com/Kegsay +.. _@Half-Shot: https://github.com/Half-Shot +.. _@aviraldg: https://github.com/aviraldg +.. _PR#310: https://github.com/matrix-org/matrix-doc/pull/310 +.. _PR#1240: https://github.com/matrix-org/matrix-doc/pull/1240 +.. _PR#1189: https://github.com/matrix-org/matrix-doc/pull/1189 +.. _PR#919: https://github.com/matrix-org/matrix-doc/pull/919 +.. _PR#1176: https://github.com/matrix-org/matrix-doc/pull/1176 \ No newline at end of file diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst new file mode 100644 index 00000000..fecfc2f9 --- /dev/null +++ b/specification/proposals_intro.rst @@ -0,0 +1,210 @@ +.. contents:: Table of Contents +.. sectnum:: + +Proposals for Spec Changes to Matrix +------------------------------------ + +The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: + +- produce a publicly-accessible proposal describing your change: + + - Please use Google Docs, or an equivalent system capable of collaborative + editing, with versioned history, suggestions ('track changes'), threaded + comments, and good mobile support. Please ensure the document is + world-commentable or -editable. + - We do not use Github issues (or Etherpad) for the design process of the + proposal, as the document review/commenting capabilities aren't good + enough. + - We also don't jump straight to PRing against the spec itself, as it's much + faster to iterate on a proposal in freeform document form than in the + terse and formal structure of the spec. + - In the proposal, please clearly state the problem being solved, and the + possible solutions being proposed for solving it and their respective + trade-offs. + - Proposal documents are intended to be as lightweight and flexible as the + author desires; there is no formal template; the intention is to iterate + as quickly as possible to get to a good design. + - A `template with suggested headers + `_ + is available. + +- make a new issue at https://github.com/matrix-org/matrix-doc/issues (or + modify an existing one), whose description should list the metadata as per + below. +- Gather feedback as widely as possible from the community and core team on + the proposal. + + - The aim is to get maximum consensus on the trade-offs chosen to get an + optimal solution. + - A good place to ask for feedback on a specific proposal is + `#matrix-spec:matrix.org `_. + However, authors/shepherds are welcome to use an alternative room if they + prefer - please advertise it in #matrix-spec:matrix.org though and link + to it on the github issue. N.B. 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); + #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 + set of trade-offs. Ideally the author would neutrally gather the various + viewpoints and get consensus, but this can sometimes be time-consuming (or + the author may be biased), in which case an impartial 'shepherd' can be + assigned to help guide the proposal through this process. A shepherd is + typically a neutral party from the core team or an experienced member of + the community. + +- Once the proposal has sufficient consensus and passed review, you **must** + show an implementation to prove that it works well in practice, before a + spec PR will be accepted. Iterate on the proposal if needed. +- Finally, please make a new spec PR which includes the changes as + implemented against + https://github.com/matrix-org/matrix-doc/tree/master/specification. This + will then be reviewed and hopefully merged! Please sign off the spec PR as + per the `CONTRIBUTING.rst + `_ + guidelines. + +Final decisions on review are made by the Matrix core team +(+matrix:matrix.org), acting on behalf of the whole Matrix community. + +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 IP. The Matrix core team pledges +to act as a neutral custodian for Matrix on behalf of the whole ecosystem, +just as it has since Matrix's inception in May 2014. + +For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That +includes client users, server admins, client developers, bot developers, +bridge and AS developers, users and admins who are indirectly using Matrix via +3rd party networks which happen to be bridged, server developers, room +moderators and admins, companies/projects building products or services on +Matrix, spec contributors, translators, and the core team who created it in +the first place. + +"Greater benefit" could include maximising: + +* the number of end-users reachable on the open Matrix network. +* the number of regular users on the Matrix network (e.g. 30-day retained + federated users) +* the number of online servers in the open federation. +* the number of developers building on Matrix. +* the number of independent implementations which use Matrix +* the quality and utility of the Matrix spec. + +The guiding principles of the overall project are being worked on as part of +the upcoming governance proposal, but could be something like: + +* Supporting the whole long-term ecosystem rather than individual stakeholder gain +* Openness rather than proprietariness +* Collaboration rather than competition +* Accessibility rather than elitism +* Transparency rather than stealth +* Empathy rather than contrariness +* Pragmatism rather than perfection +* Proof rather than conjecture + +The above directions are intended to be simple and pragmatic rather than +exhaustive, and aim to provide guidelines until we have a formal spec +governance process in place that covers the whole Matrix community. In order +to get Matrix out of beta as quickly as possible, as of May 2018 we are +prioritising spec and reference implementation development over writing formal +governance, but a formal governance document will follow as rapidly as +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 +`_. + +:: + + + + + Proposals | Spec PRs | Other States + +-------+ | +------+ | +----------+ + | | + | | + +----------+ | +---------+ | +---------+ + | | | | | | | | + | Proposal | | +------> Spec PR | | | Blocked | + | WIP | | | | Missing | | | | + | | | | | | | +---------+ + +----+-----+ | | +----+----+ | + | | | | | + | | | | | +-----------+ + +--------v----------+ | | | | | | + | | | | +---------v--------+ | | Abandoned | + | Proposal | | | | | | | | + | Ready for Review | | | | Spec PR | | +-----------+ + | | | | | Ready for Review | | + +----------+--------+ | | | | | +-----------+ + | | | +---------+--------+ | | | + | | | | | | Obsolete | + +------v----+ | | | | | | + | | | | +-----v-----+ | +-----------+ + | Proposal | | | | | | + | In Review | | | | Spec PR | | + | | | | | In Review | | +----------+ + +----+------+ | | | | | | | + | | | +-----+-----+ | | Rejected | + | | | | | | | + +------v--------+ | | | | +----------+ + | | | | | | + | Proposal | | | +----v----+ | + | Passed Review | | | | | | + | | | | | Merged! | | + +-------+-------+ | | | | | + | | | +---------+ | + | | | | + +---------------+ | + | | + + + + +Lifetime States +--------------- + +=========================== ======================================================= +Proposal WIP A proposal document which is still work-in-progress but is being shared to incorporate feedback +Proposal Ready for Review A proposal document which is now ready and waiting for review by the core team and community +Proposal In Review A proposal document which is currently in review +Proposal Passed Review A proposal document which has passed review as worth implementing and then being added to the spec +Spec PR Missing A proposal which has been implemented and has been used in the wild for a few months but hasn't yet been added to the spec +Spec PR Ready for Review A proposal which has been PR'd against the spec and is awaiting review +Spec PR In Review A proposal which has been PR'd against the spec and is in review +Merged A proposal whose PR has merged into the spec! +Blocked A proposal which is temporarily blocked on some external factor (e.g. being blocked on another proposal first being approved) +Abandoned A proposal where the author/shepherd has not been responsive for a few months +Obsolete A proposal which has been overtaken by other proposals +Rejected A proposal which is not going to be incorporated into Matrix +=========================== ======================================================= + + +Proposal Tracking +----------------- + +This is a living document generated from the list of proposals at +`matrix-doc/issues `_ on +GitHub. + +We use labels and some metadata in the issues' 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. + +Other metadata: + +- the MSC (Matrix Spec Change) number is taken from the github issue ID. This + is carried for the lifetime of the proposal, including the PR creation + phase. N.B. They are not in chronological order! +- Please use the github issue title to set the title. +- Please link to the proposal document by adding a "Documentation: " line + in the issue description. +- Please link to the spec PR (if any) by adding a "PRs: #1234" line in the + issue description. +- The creation date is taken from the github issue, but can be overriden by + adding a "Date: yyyy-mm-dd" line in the issue description. +- Updated Date is taken from github. +- Author is the creator of the github issue, but can be overriden by adding a + "Author: @username" line in the body of the issue description. Please make + sure @username is a github user (include 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. diff --git a/specification/targets.yaml b/specification/targets.yaml index 50a9fb8d..8ca5ce30 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -38,6 +38,10 @@ targets: - appendices/threepids.rst - appendices/threat_model.rst - appendices/test_vectors.rst + proposals: + files: + - proposals_intro.rst + - proposals.rst groups: # reusable blobs of files when prefixed with 'group:' modules: - modules/instant_messaging.rst