From e18aa30fd26cf77ad27825381371ad924adddc9d Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Wed, 2 May 2018 13:47:01 +0100 Subject: [PATCH 01/40] start generating new proposals page --- scripts/proposals.py | 50 +++++++++++++++++++++++++++++++ specification/proposals.rst | 5 ++++ specification/proposals_intro.rst | 20 +++++++++++++ specification/targets.yaml | 4 +++ 4 files changed, 79 insertions(+) create mode 100644 scripts/proposals.py create mode 100644 specification/proposals.rst create mode 100644 specification/proposals_intro.rst diff --git a/scripts/proposals.py b/scripts/proposals.py new file mode 100644 index 000000000..1e4b8683a --- /dev/null +++ b/scripts/proposals.py @@ -0,0 +1,50 @@ +# proposals.py: generate an RST file (proposals.rst) from queries to github.com/matrix.org/matrix-doc/issues. +# v0.0.1 +# todo: +# use status labels to create separate sections. +# include all fields discussed at https://docs.google.com/document/d/1wLln7da12l0H5YgAh5xM2TVE7VsTjXzhEwVh3sRBMCk/edit# +# format, probably as tables + +import requests +import re +from m2r import convert as m2r + +def getpage(url, page): + resp = requests.get(url + str(page)) + json.extend(resp.json()) + + for link in resp.links.values(): + if link['rel'] == 'last': + return re.search('page=(.+?)', link['url']).group(1) + +json = list() +print("json:" + str(len(json))) +pagecount = getpage('https://api.github.com/repos/matrix-org/matrix-doc/issues?labels=spec-omission&state=open&page=', 1) +print("json:" + str(len(json))) +print("pagecount:" + str(pagecount)) +for page in range(2, int(pagecount) + 1): + getpage('https://api.github.com/repos/matrix-org/matrix-doc/issues?labels=spec-omission&state=open&page=', page) + print("json:" + str(len(json))) + print("currentpage:" + str(page)) + print("pagecount:" + str(pagecount)) + print("json:" + str(len(json))) + + +text_file = open("../specification/proposals.rst", "w") + +text_file.write(".. contents:: Table of Contents\n") +text_file.write(".. sectnum::") +text_file.write("\n") +text_file.write("\n") +text_file.write("The Proposals List\n------------------\n") +# text_file.write(json[0]['user']['login']) + +for item in json: + prop_header = item['title'] + " (" + str(item['number']) + ")" + text_file.write(prop_header + "\n") + text_file.write("~" * len(prop_header)) + text_file.write("\n\n") + body = m2r(str(item['body'])) + text_file.write(body + "\n\n\n") + +text_file.close() diff --git a/specification/proposals.rst b/specification/proposals.rst new file mode 100644 index 000000000..5a1f02c07 --- /dev/null +++ b/specification/proposals.rst @@ -0,0 +1,5 @@ +.. contents:: Table of Contents +.. sectnum:: + +The Proposals List +------------------ diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst new file mode 100644 index 000000000..672c34681 --- /dev/null +++ b/specification/proposals_intro.rst @@ -0,0 +1,20 @@ +.. contents:: Table of Contents +.. sectnum:: + +Proposals for Spec Changes to 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 issue text to generate this page. When adding or updating an issue, make sure you specify the current status as a label: + +- WIP +- Ready for review +- In review +- Merged +- Rejected +- Stalled + diff --git a/specification/targets.yaml b/specification/targets.yaml index 50a9fb8d5..8ca5ce303 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 From 1f7fbefd53394120411d8af10d0198548cfe8d27 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 8 May 2018 12:17:38 +0100 Subject: [PATCH 02/40] start using a table --- scripts/proposals.py | 50 +++++++++++++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 12 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 1e4b8683a..4ba4d0ee6 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -7,6 +7,7 @@ import requests import re +from datetime import datetime from m2r import convert as m2r def getpage(url, page): @@ -18,32 +19,57 @@ def getpage(url, page): return re.search('page=(.+?)', link['url']).group(1) json = list() -print("json:" + str(len(json))) +# labels = ['p1', p2] +# new status labels: +# proposal-ready-for-review,rejected,stalled,merged,spec-pr-in-review,proposal-wip,proposal-in-review,spec-pr-ready-for-review,proposal-passed-review +urlbase = 'https://api.github.com/repos/matrix-org/matrix-doc/issues?labels=p1,p2,p3,p4,p5&state=open&page=' pagecount = getpage('https://api.github.com/repos/matrix-org/matrix-doc/issues?labels=spec-omission&state=open&page=', 1) -print("json:" + str(len(json))) -print("pagecount:" + str(pagecount)) for page in range(2, int(pagecount) + 1): - getpage('https://api.github.com/repos/matrix-org/matrix-doc/issues?labels=spec-omission&state=open&page=', page) - print("json:" + str(len(json))) - print("currentpage:" + str(page)) - print("pagecount:" + str(pagecount)) - print("json:" + str(len(json))) + getpage(urlbase, page) text_file = open("../specification/proposals.rst", "w") -text_file.write(".. contents:: Table of Contents\n") -text_file.write(".. sectnum::") -text_file.write("\n") +text_file.write("Tables\n------------------\n\n.. list-table::\n :header-rows: 1\n\n") + +text_file.write(" * - ID\n") +text_file.write(" - github username\n") +text_file.write(" - proposal title\n") +text_file.write(" - created_at\n") +text_file.write(" - updated_at\n") +text_file.write(" - maindoc\n") + +#`matrix-doc/issues `_ +for item in json: + maindoc = re.search('Documentation: (.+?)\n', str(item['body'])) + if maindoc is not None: + maindoc = maindoc.group(1) + text_file.write(" * - `" + str(item['number']) + " <" + item['html_url'] + ">`_\n") + text_file.write(" - " + item['user']['login'] + "\n") + text_file.write(" - " + item['title'] + "\n") + text_file.write(" - " + item['created_at'] + "\n") + text_file.write(" - " + item['updated_at'] + "\n") + text_file.write(" - " + str(maindoc) + "\n") + text_file.write("\n") + + text_file.write("The Proposals List\n------------------\n") # text_file.write(json[0]['user']['login']) - for item in json: + # write a header prop_header = item['title'] + " (" + str(item['number']) + ")" text_file.write(prop_header + "\n") text_file.write("~" * len(prop_header)) text_file.write("\n\n") + + # write some metadata + text_file.write(item['created_at'] + "\n") + text_file.write(item['updated_at'] + "\n") + # created = datetime.strptime(item['created_at'], "%Y-%m-%dT%XZ") + + + # write body text body = m2r(str(item['body'])) text_file.write(body + "\n\n\n") From c58dc59ffe89c3f3e8bf232a53ea490ef7861a55 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 8 May 2018 14:43:06 +0100 Subject: [PATCH 03/40] separate tables by label --- scripts/proposals.py | 103 +++++++++++++++++++++++++------------------ 1 file changed, 60 insertions(+), 43 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 4ba4d0ee6..171db0691 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -10,67 +10,84 @@ import re from datetime import datetime from m2r import convert as m2r +pagecount = 1 + def getpage(url, page): resp = requests.get(url + str(page)) - json.extend(resp.json()) for link in resp.links.values(): if link['rel'] == 'last': - return re.search('page=(.+?)', link['url']).group(1) + 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 -json = list() -# labels = ['p1', p2] # new status labels: # proposal-ready-for-review,rejected,stalled,merged,spec-pr-in-review,proposal-wip,proposal-in-review,spec-pr-ready-for-review,proposal-passed-review -urlbase = 'https://api.github.com/repos/matrix-org/matrix-doc/issues?labels=p1,p2,p3,p4,p5&state=open&page=' -pagecount = getpage('https://api.github.com/repos/matrix-org/matrix-doc/issues?labels=spec-omission&state=open&page=', 1) -for page in range(2, int(pagecount) + 1): - getpage(urlbase, page) +labels = ['p1', 'p2'] +issues = {} +for label in labels: + issues[label] = getbylabel(label) + print(issues) text_file = open("../specification/proposals.rst", "w") -text_file.write("Tables\n------------------\n\n.. list-table::\n :header-rows: 1\n\n") - -text_file.write(" * - ID\n") -text_file.write(" - github username\n") -text_file.write(" - proposal title\n") -text_file.write(" - created_at\n") -text_file.write(" - updated_at\n") -text_file.write(" - maindoc\n") - -#`matrix-doc/issues `_ -for item in json: - maindoc = re.search('Documentation: (.+?)\n', str(item['body'])) - if maindoc is not None: - maindoc = maindoc.group(1) - text_file.write(" * - `" + str(item['number']) + " <" + item['html_url'] + ">`_\n") - text_file.write(" - " + item['user']['login'] + "\n") - text_file.write(" - " + item['title'] + "\n") - text_file.write(" - " + item['created_at'] + "\n") - text_file.write(" - " + item['updated_at'] + "\n") - text_file.write(" - " + str(maindoc) + "\n") +text_file.write("Tables\n------------------\n\n") + + +for label in labels: + text_file.write(label + "\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n") + text_file.write(".. list-table::\n :header-rows: 1\n :widths: auto\n\n") + text_file.write(" * - ID\n") + text_file.write(" - github username\n") + text_file.write(" - proposal title\n") + text_file.write(" - created_at\n") + text_file.write(" - updated_at\n") + text_file.write(" - maindoc\n") + + for item in issues[label]: + maindoc = re.search('Documentation: (.+?)\n', str(item['body'])) + if maindoc is not None: + maindoc = maindoc.group(1) + text_file.write(" * - `" + str(item['number']) + " <" + item['html_url'] + ">`_\n") + text_file.write(" - " + item['user']['login'] + "\n") + text_file.write(" - " + item['title'] + "\n") + text_file.write(" - " + item['created_at'] + "\n") + text_file.write(" - " + item['updated_at'] + "\n") + text_file.write(" - " + str(maindoc) + "\n") + text_file.write("\n\n\n") text_file.write("\n") -text_file.write("The Proposals List\n------------------\n") -# text_file.write(json[0]['user']['login']) -for item in json: - # write a header - prop_header = item['title'] + " (" + str(item['number']) + ")" - text_file.write(prop_header + "\n") - text_file.write("~" * len(prop_header)) - text_file.write("\n\n") +# text_file.write("The Proposals List\n------------------\n") +# # text_file.write(json[0]['user']['login']) +# for item in json: +# # write a header +# prop_header = item['title'] + " (" + str(item['number']) + ")" +# text_file.write(prop_header + "\n") +# text_file.write("~" * len(prop_header)) +# text_file.write("\n\n") - # write some metadata - text_file.write(item['created_at'] + "\n") - text_file.write(item['updated_at'] + "\n") - # created = datetime.strptime(item['created_at'], "%Y-%m-%dT%XZ") +# # write some metadata +# text_file.write(item['created_at'] + "\n") +# text_file.write(item['updated_at'] + "\n") +# # created = datetime.strptime(item['created_at'], "%Y-%m-%dT%XZ") - # write body text - body = m2r(str(item['body'])) - text_file.write(body + "\n\n\n") +# # write body text +# body = m2r(str(item['body'])) +# text_file.write(body + "\n\n\n") text_file.close() From 9e37d15c8fce944c458068f7c94aae7c08daed02 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 8 May 2018 15:11:15 +0100 Subject: [PATCH 04/40] little ascii diagram of process --- specification/proposals_intro.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 672c34681..ebc43b9a9 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -4,6 +4,7 @@ Proposals for Spec Changes to Matrix ------------------------------------ + Proposal Tracking ----------------- @@ -18,3 +19,28 @@ We use labels and some metadata in the issue text to generate this page. When ad - Rejected - Stalled +:: + + +----------+ +-------------------+ +-----------+ +---------------+ + | | | | | | | | + | Proposal +-----> Proposal +-----> Proposal +-----> Proposal +------+ + | WIP | | Ready for Review | | In Review | | Passed Review | | + | | | | | | | | | + +----------+ +-------------------+ +-----------+ +---------------+ | + | + +---------------------------------------------------------------------------------------+ + | + | +---------------------+ +-----------+ +-----------+ + | | | | | |-----------| + +--> Spec +-----> Spec PR | || || + | PR Ready for Review | | In Review +-----------------------> Merged || + | | | | || || + +---------------------+ +-+-------+-+ |-----------| + | | +-----------+ + +-------+ +--------+ + | | + +-----v----+ +-----v----+ + | | | | + | Stalled | | Rejected | + | | | | + +----------+ +----------+ From a78f7b38e9d565d7e1af4d62159a4296bf65ede2 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 8 May 2018 15:35:46 +0100 Subject: [PATCH 05/40] generator is now usable --- scripts/proposals.py | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 171db0691..5bc3b9584 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -33,8 +33,10 @@ def getbylabel(label): return json # new status labels: -# proposal-ready-for-review,rejected,stalled,merged,spec-pr-in-review,proposal-wip,proposal-in-review,spec-pr-ready-for-review,proposal-passed-review -labels = ['p1', 'p2'] +# labels = ['proposal-wip', 'proposal-ready-for-review', +# 'proposal-in-review', 'proposal-passed-review', +# 'spec-pr-ready-for-review', 'spec-pr-in-review', 'merged', 'stalled', 'rejected' ] +labels = ['p1', 'p2', 'p3', 'p4', 'p5'] issues = {} for label in labels: @@ -49,23 +51,33 @@ text_file.write("Tables\n------------------\n\n") for label in labels: text_file.write(label + "\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n") text_file.write(".. list-table::\n :header-rows: 1\n :widths: auto\n\n") - text_file.write(" * - ID\n") + text_file.write(" * - MSC\n") text_file.write(" - github username\n") text_file.write(" - proposal title\n") text_file.write(" - created_at\n") text_file.write(" - updated_at\n") text_file.write(" - maindoc\n") + text_file.write(" - author\n") + text_file.write(" - shepherd\n") for item in issues[label]: - maindoc = re.search('Documentation: (.+?)\n', str(item['body'])) - if maindoc is not None: - maindoc = maindoc.group(1) - text_file.write(" * - `" + str(item['number']) + " <" + item['html_url'] + ">`_\n") + text_file.write(" * - `MSC" + str(item['number']) + " <" + item['html_url'] + ">`_\n") text_file.write(" - " + item['user']['login'] + "\n") text_file.write(" - " + item['title'] + "\n") - text_file.write(" - " + item['created_at'] + "\n") - text_file.write(" - " + item['updated_at'] + "\n") + created = datetime.strptime(item['created_at'], "%Y-%m-%dT%XZ") + text_file.write(" - " + created.strftime('%Y-%m-%d') + "\n") + updated = datetime.strptime(item['updated_at'], "%Y-%m-%dT%XZ") + text_file.write(" - " + updated.strftime('%Y-%m-%d') + "\n") + maindoc = re.search('Documentation: (.+?)\n', str(item['body'])) + if maindoc is not None: maindoc = maindoc.group(1) text_file.write(" - " + str(maindoc) + "\n") + author = re.search('Author: (.+?)\n', str(item['body'])) + if author is not None: author = author.group(1) + #if author is None: author = item['user']['login'] + text_file.write(" - " + str(author) + "\n") + shepherd = re.search('Shepherd: (.+?)\n', str(item['body'])) + if shepherd is not None: shepherd = shepherd.group(1) + text_file.write(" - " + str(shepherd) + "\n") text_file.write("\n\n\n") text_file.write("\n") From dc2b53318b38f84d0a7e373a5450452c779ddd8b Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Wed, 9 May 2018 11:32:31 +0100 Subject: [PATCH 06/40] prettify ID column --- scripts/proposals.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 5bc3b9584..62a94dbaf 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -50,7 +50,7 @@ text_file.write("Tables\n------------------\n\n") for label in labels: text_file.write(label + "\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n") - text_file.write(".. list-table::\n :header-rows: 1\n :widths: auto\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(" - github username\n") text_file.write(" - proposal title\n") From 866b0b6348dc6a052f41c76319e8b62b61cf915a Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Thu, 10 May 2018 16:02:55 +0100 Subject: [PATCH 07/40] I mostly play with ascii art --- scripts/proposals.py | 15 +++++--- specification/proposals_intro.rst | 64 ++++++++++++++++++++----------- 2 files changed, 50 insertions(+), 29 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 62a94dbaf..075e31182 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -33,10 +33,10 @@ def getbylabel(label): return json # new status labels: -# labels = ['proposal-wip', 'proposal-ready-for-review', -# 'proposal-in-review', 'proposal-passed-review', -# 'spec-pr-ready-for-review', 'spec-pr-in-review', 'merged', 'stalled', 'rejected' ] -labels = ['p1', 'p2', 'p3', 'p4', 'p5'] +labels = ['proposal-wip', 'proposal-ready-for-review', + 'proposal-in-review', 'proposal-passed-review', + 'spec-pr-ready-for-review', 'spec-pr-in-review', 'merged', 'abandoned', 'rejected', 'blocked' ] +#labels = ['p1', 'p2', 'p3', 'p4', 'p5'] issues = {} for label in labels: @@ -49,6 +49,9 @@ text_file.write("Tables\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") @@ -68,10 +71,10 @@ for label in labels: text_file.write(" - " + created.strftime('%Y-%m-%d') + "\n") updated = datetime.strptime(item['updated_at'], "%Y-%m-%dT%XZ") text_file.write(" - " + updated.strftime('%Y-%m-%d') + "\n") - maindoc = re.search('Documentation: (.+?)\n', str(item['body'])) + maindoc = re.search('^Documentation: (.+?)\n', str(item['body'])) if maindoc is not None: maindoc = maindoc.group(1) text_file.write(" - " + str(maindoc) + "\n") - author = re.search('Author: (.+?)\n', str(item['body'])) + author = re.search('^Author: (.+?)\n', str(item['body']), flags=re.MULTILINE) if author is not None: author = author.group(1) #if author is None: author = item['user']['login'] text_file.write(" - " + str(author) + "\n") diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index ebc43b9a9..3f3f5caa4 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -21,26 +21,44 @@ We use labels and some metadata in the issue text to generate this page. When ad :: - +----------+ +-------------------+ +-----------+ +---------------+ - | | | | | | | | - | Proposal +-----> Proposal +-----> Proposal +-----> Proposal +------+ - | WIP | | Ready for Review | | In Review | | Passed Review | | - | | | | | | | | | - +----------+ +-------------------+ +-----------+ +---------------+ | - | - +---------------------------------------------------------------------------------------+ - | - | +---------------------+ +-----------+ +-----------+ - | | | | | |-----------| - +--> Spec +-----> Spec PR | || || - | PR Ready for Review | | In Review +-----------------------> Merged || - | | | | || || - +---------------------+ +-+-------+-+ |-----------| - | | +-----------+ - +-------+ +--------+ - | | - +-----v----+ +-----v----+ - | | | | - | Stalled | | Rejected | - | | | | - +----------+ +----------+ + + + + Proposals | Spec PRs | Other States + +-------+ | +------+ | +----------+ + | | + | | + +----------+ | +------------------+ | +---------+ + | | | | | | | | + | Proposal | | +-> Spec PR | | | Blocked | + | WIP | | | | Ready for Review | | | | + | | | | | | | +---------+ + +----+-----+ | | +---------+--------+ | + | | | | | + | | | | | +-----------+ + +--------v----------+ | | +-----v-----+ | | | + | | | | | | | | Abandoned | + | Proposal | | | | Spec PR | | | | + | Ready for Review | | | | In Review | | +-----------+ + | | | | | | | + +----------+--------+ | | +-----+-----+ | +-----------+ + | | | | | | | + | | | | | | Obsolete | + +------v----+ | | | | | | + | | | | +-----------+ | +-----------+ + | Proposal | | | |-----v-----| | + | In Review | | | || || | + | | | | || Merged || | +----------+ + +----+------+ | | || || | | | + | | | |-----------| | | Rejected | + | | | +-----------+ | | | + +------v--------+ | | | +----------+ + | | | | | + | Proposal | | | | + | Passed Review | | | | + | | | | | + +-------+-------+ | | | + | | | | + | | | | + +---------------+ | + | | + + + + From 73b7faddd4565cfbe9a6c17f0ddf263174feb73c Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Fri, 11 May 2018 20:47:27 +0100 Subject: [PATCH 08/40] handle multiple Google Docs --- scripts/proposals.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 075e31182..dcd49b881 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -51,7 +51,7 @@ text_file.write("Tables\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") @@ -72,8 +72,13 @@ for label in labels: updated = datetime.strptime(item['updated_at'], "%Y-%m-%dT%XZ") text_file.write(" - " + updated.strftime('%Y-%m-%d') + "\n") maindoc = re.search('^Documentation: (.+?)\n', str(item['body'])) - if maindoc is not None: maindoc = maindoc.group(1) - text_file.write(" - " + str(maindoc) + "\n") + 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 = re.search('^Author: (.+?)\n', str(item['body']), flags=re.MULTILINE) if author is not None: author = author.group(1) #if author is None: author = item['user']['login'] From cbdd33a5f5da544295fe4ff130678f59337555ea Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Fri, 11 May 2018 21:23:06 +0100 Subject: [PATCH 09/40] single authors and shepherds link correctly --- scripts/proposals.py | 35 +++++++++++------------------------ 1 file changed, 11 insertions(+), 24 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index dcd49b881..138a589c2 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -11,6 +11,7 @@ from datetime import datetime from m2r import convert as m2r pagecount = 1 +authors = set() def getpage(url, page): resp = requests.get(url + str(page)) @@ -55,7 +56,7 @@ for label in labels: 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(" - github username\n") + #text_file.write(" - github username\n") text_file.write(" - proposal title\n") text_file.write(" - created_at\n") text_file.write(" - updated_at\n") @@ -65,7 +66,7 @@ for label in labels: for item in issues[label]: text_file.write(" * - `MSC" + str(item['number']) + " <" + item['html_url'] + ">`_\n") - text_file.write(" - " + item['user']['login'] + "\n") + #text_file.write(" - " + item['user']['login'] + "\n") text_file.write(" - " + item['title'] + "\n") created = datetime.strptime(item['created_at'], "%Y-%m-%dT%XZ") text_file.write(" - " + created.strftime('%Y-%m-%d') + "\n") @@ -81,33 +82,19 @@ for label in labels: text_file.write("\n") author = re.search('^Author: (.+?)\n', str(item['body']), flags=re.MULTILINE) if author is not None: author = author.group(1) - #if author is None: author = item['user']['login'] - text_file.write(" - " + str(author) + "\n") + else: author = "@" + item['user']['login'] + authors.add(author.strip()) + text_file.write(" - `" + str(author.strip()) + "`_" + "\n") shepherd = re.search('Shepherd: (.+?)\n', str(item['body'])) - if shepherd is not None: shepherd = shepherd.group(1) + if shepherd is not None: + authors.add(shepherd.group(1).strip()) + shepherd = "`" + shepherd.group(1).strip() + "`_" text_file.write(" - " + str(shepherd) + "\n") text_file.write("\n\n\n") text_file.write("\n") - -# text_file.write("The Proposals List\n------------------\n") -# # text_file.write(json[0]['user']['login']) -# for item in json: -# # write a header -# prop_header = item['title'] + " (" + str(item['number']) + ")" -# text_file.write(prop_header + "\n") -# text_file.write("~" * len(prop_header)) -# text_file.write("\n\n") - -# # write some metadata -# text_file.write(item['created_at'] + "\n") -# text_file.write(item['updated_at'] + "\n") -# # created = datetime.strptime(item['created_at'], "%Y-%m-%dT%XZ") - - -# # write body text -# body = m2r(str(item['body'])) -# text_file.write(body + "\n\n\n") +for author in authors: + text_file.write("\n.. _" + author + ": https://github.com/" + author[1:]) text_file.close() From 3b84de383c2b825f3197edc6ddfe4f01b23f90e2 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Sat, 12 May 2018 10:30:52 +0100 Subject: [PATCH 10/40] cleanup and include all content --- scripts/proposals.py | 40 ++++++++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 138a589c2..c3d65678f 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -56,7 +56,6 @@ for label in labels: 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(" - github username\n") text_file.write(" - proposal title\n") text_file.write(" - created_at\n") text_file.write(" - updated_at\n") @@ -65,13 +64,26 @@ for label in labels: text_file.write(" - shepherd\n") for item in issues[label]: + # MSC number text_file.write(" * - `MSC" + str(item['number']) + " <" + item['html_url'] + ">`_\n") - #text_file.write(" - " + item['user']['login'] + "\n") + + # title from Github issue text_file.write(" - " + item['title'] + "\n") - created = datetime.strptime(item['created_at'], "%Y-%m-%dT%XZ") - text_file.write(" - " + created.strftime('%Y-%m-%d') + "\n") + + # created date, find local field, otherwise Github + created = re.search('^Date: (.+?)\n', str(item['body']), flags=re.MULTILINE) + if created is not None: + created = created.group(1).strip() + else : + created = datetime.strptime(item['created_at'], "%Y-%m-%dT%XZ") + created = created.strftime('%Y-%m-%d') + text_file.write(" - " + 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) @@ -80,11 +92,23 @@ for label in labels: else: text_file.write(" - ") text_file.write("\n") + + # author list, if missing just use Github issue creator author = re.search('^Author: (.+?)\n', str(item['body']), flags=re.MULTILINE) - if author is not None: author = author.group(1) - else: author = "@" + item['user']['login'] - authors.add(author.strip()) - text_file.write(" - `" + str(author.strip()) + "`_" + "\n") + 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 (currnely only one) shepherd = re.search('Shepherd: (.+?)\n', str(item['body'])) if shepherd is not None: authors.add(shepherd.group(1).strip()) From 3b4e56c4e085bc33bd9ae58c870c4f6558699b8d Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Mon, 14 May 2018 09:48:54 +0100 Subject: [PATCH 11/40] handle dd/mm/yyyy and yyyy-mm-dd dates in text --- scripts/proposals.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/scripts/proposals.py b/scripts/proposals.py index c3d65678f..a27961ff4 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -74,6 +74,18 @@ for label in labels: created = re.search('^Date: (.+?)\n', str(item['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') From 867307af8be08fae5420b58e3beaba88b0e3656b Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Mon, 14 May 2018 09:57:43 +0100 Subject: [PATCH 12/40] new flow --- specification/proposals_intro.rst | 55 ++++++++++++++++--------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 3f3f5caa4..d5687d015 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -26,39 +26,40 @@ We use labels and some metadata in the issue text to generate this page. When ad +-------+ | +------+ | +----------+ | | | | - +----------+ | +------------------+ | +---------+ - | | | | | | | | - | Proposal | | +-> Spec PR | | | Blocked | - | WIP | | | | Ready for Review | | | | - | | | | | | | +---------+ - +----+-----+ | | +---------+--------+ | + +----------+ | +---------+ | +---------+ + | | | | | | | | + | Proposal | | +------> Spec PR | | | Blocked | + | WIP | | | | Missing | | | | + | | | | | | | +---------+ + +----+-----+ | | +----+----+ | | | | | | | | | | | +-----------+ - +--------v----------+ | | +-----v-----+ | | | - | | | | | | | | Abandoned | - | Proposal | | | | Spec PR | | | | - | Ready for Review | | | | In Review | | +-----------+ - | | | | | | | - +----------+--------+ | | +-----+-----+ | +-----------+ - | | | | | | | + +--------v----------+ | | | | | | + | | | | +---------v--------+ | | Abandoned | + | Proposal | | | | | | | | + | Ready for Review | | | | Spec PR | | +-----------+ + | | | | | Ready for Review | | + +----------+--------+ | | | | | +-----------+ + | | | +---------+--------+ | | | | | | | | | Obsolete | +------v----+ | | | | | | - | | | | +-----------+ | +-----------+ - | Proposal | | | |-----v-----| | - | In Review | | | || || | - | | | | || Merged || | +----------+ - +----+------+ | | || || | | | - | | | |-----------| | | Rejected | - | | | +-----------+ | | | - +------v--------+ | | | +----------+ - | | | | | - | Proposal | | | | - | Passed Review | | | | - | | | | | - +-------+-------+ | | | - | | | | + | | | | +-----v-----+ | +-----------+ + | Proposal | | | | | | + | In Review | | | | Spec PR | | + | | | | | In Review | | +----------+ + +----+------+ | | | | | | | + | | | +-----+-----+ | | Rejected | + | | | | | | | + +------v--------+ | | | | +----------+ + | | | | | | + | Proposal | | | +----v----+ | + | Passed Review | | | | | | + | | | | | Merged! | | + +-------+-------+ | | | | | + | | | +---------+ | | | | | +---------------+ | | | + + + From 120fa92078f28202b949e0068893fbd78f30dbff Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Mon, 14 May 2018 10:25:10 +0100 Subject: [PATCH 13/40] update intro --- specification/proposals_intro.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index d5687d015..c87f5d1d4 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -10,14 +10,17 @@ 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 issue text to generate this page. When adding or updating an issue, make sure you specify the current status as a label: +We use labels and some metadata in the issue text to generate this page. When adding or updating an issue, make sure you specify the current status as a label per the diagram below, these labels already exist in the matrix-doc repo. + +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. +- Please use the github issue title to set the title. +- The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text. +- 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 text. Please make sure @username is a github user (include the @!) +- Shepherd is set by adding a "Shepherd: @username" line in the body of the issue text. Again, make sure this is a real Github user. -- WIP -- Ready for review -- In review -- Merged -- Rejected -- Stalled :: From e87f1f26198a14d837a0bfe3a0953fb8ca052c3b Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Mon, 14 May 2018 11:32:40 +0100 Subject: [PATCH 14/40] include PRs in tables --- scripts/proposals.py | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index a27961ff4..aa9ba5d31 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -12,6 +12,7 @@ from m2r import convert as m2r pagecount = 1 authors = set() +prs = set() def getpage(url, page): resp = requests.get(url + str(page)) @@ -35,8 +36,8 @@ def getbylabel(label): # new status labels: labels = ['proposal-wip', 'proposal-ready-for-review', - 'proposal-in-review', 'proposal-passed-review', - 'spec-pr-ready-for-review', 'spec-pr-in-review', 'merged', 'abandoned', 'rejected', 'blocked' ] + '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 = {} @@ -56,12 +57,13 @@ for label in labels: 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(" - created_at\n") - text_file.write(" - updated_at\n") - text_file.write(" - maindoc\n") - text_file.write(" - author\n") - text_file.write(" - shepherd\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]: # MSC number @@ -126,6 +128,20 @@ for label in labels: authors.add(shepherd.group(1).strip()) shepherd = "`" + shepherd.group(1).strip() + "`_" text_file.write(" - " + str(shepherd) + "\n") + + # PRs + pr_list = re.search('PRs: (.+?)\n', 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") @@ -133,4 +149,7 @@ 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) + text_file.close() From b8f38b21a7627adfccdb868416aaa23fd55ee075 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Mon, 14 May 2018 14:25:12 +0100 Subject: [PATCH 15/40] update introductory text --- scripts/proposals.py | 2 +- specification/proposals_intro.rst | 35 +++++++++++++++++-------------- 2 files changed, 20 insertions(+), 17 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index aa9ba5d31..0b0717d95 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -47,7 +47,7 @@ for label in labels: text_file = open("../specification/proposals.rst", "w") -text_file.write("Tables\n------------------\n\n") +text_file.write("Tables of Tracked Proposals\n---------------------------\n\n") for label in labels: diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index c87f5d1d4..d6d79c929 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -3,24 +3,13 @@ Proposals for Spec Changes to Matrix ------------------------------------ +The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: +- produce a publicly-accessible Google Doc describing you change +- make a new issue at https://github.com/matrix-org/matrix-doc/issues with the metadata appropriate to the section below +- make a new PR which includes the proposed changed at https://github.com/matrix-org/matrix-doc/tree/master/specification -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 issue text to generate this page. When adding or updating an issue, make sure you specify the current status as a label per the diagram below, these labels already exist in the matrix-doc repo. - -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. -- Please use the github issue title to set the title. -- The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text. -- 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 text. Please make sure @username is a github user (include the @!) -- Shepherd is set by adding a "Shepherd: @username" line in the body of the issue text. Again, make sure this is a real Github user. - +The process for handling proposals is described in the following diagram. Note that there are corresponding labels for each stage available in the matrix-doc issue tracker. :: @@ -65,4 +54,18 @@ Other metadata: | | + + +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 issue text to generate this page. When adding or updating an issue, make sure you specify the current status as a label per the diagram above, these labels already exist in the matrix-doc repo. + +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. +- Please use the github issue title to set the title. +- The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text. +- 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 text. Please make sure @username is a github user (include the @!) +- Shepherd is set by adding a "Shepherd: @username" line in the body of the issue text. Again, make sure this is a real Github user. From 8c469e51cbf01caca3f2551e367dcd74de66d36d Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 May 2018 22:05:28 +0100 Subject: [PATCH 16/40] lots of tweaks to the MSC verbiage --- specification/proposals_intro.rst | 47 +++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index d6d79c929..f1a3adb65 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -3,13 +3,23 @@ Proposals for Spec Changes to Matrix ------------------------------------ + The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: -- produce a publicly-accessible Google Doc describing you change -- make a new issue at https://github.com/matrix-org/matrix-doc/issues with the metadata appropriate to the section below -- make a new PR which includes the proposed changed at https://github.com/matrix-org/matrix-doc/tree/master/specification +- produce a publicly-accessible proposal describing your change: + - Please use Google Docs, or an equivalent system capable of collaborative editing, with versioned history and threaded comments. + - 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 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. +- make a new issue at https://github.com/matrix-org/matrix-doc/issues, 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. + - Iterating on the proposal and getting consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. +- Once the proposal has consensus and passed review, you **must** show an implementation to prove that it works well in practice, before before a spec PR will be accepted. Iterate on the proposal if needed. +- Finally, please make a new spec PR which includes the proposed changes against https://github.com/matrix-org/matrix-doc/tree/master/specification. This will then be reviewed and hopefully merged! -The process for handling proposals is described in the following diagram. Note that there are corresponding labels for each stage available in the matrix-doc issue tracker. +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 `_. :: @@ -54,18 +64,37 @@ The process for handling proposals is described in the following diagram. Note t | | + + +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 is being used in the wild 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 is not responsive +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. +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 issue text to generate this page. When adding or updating an issue, make sure you specify the current status as a label per the diagram above, these labels already exist in the matrix-doc repo. +We use labels and some metadata in the issue's description 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. +- 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. -- The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text. +- The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text. - 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 text. Please make sure @username is a github user (include the @!) -- Shepherd is set by adding a "Shepherd: @username" line in the body of the issue text. Again, make sure this is a real Github user. +- Shepherd is set by adding a "Shepherd: @username" line in the issue description. Again, make sure this is a real Github user. From cb882ba12d16c5fdae98706d5487a91745a5e78b Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 May 2018 22:07:49 +0100 Subject: [PATCH 17/40] more tweaks --- specification/proposals_intro.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index f1a3adb65..6bdc653a7 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -94,7 +94,8 @@ 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. -- The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text. +- Please link to the proposal document by adding a "Documentation: " 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 text. Please make sure @username is a github user (include the @!) -- Shepherd is set by adding a "Shepherd: @username" line in the issue description. Again, make sure this is a real Github user. +- 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. From 93681458d691fc978181dd4839e9217e563eb0a1 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 May 2018 22:13:28 +0100 Subject: [PATCH 18/40] more tweaks --- specification/proposals_intro.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 6bdc653a7..e1024e575 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -12,11 +12,11 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: - 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 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. -- make a new issue at https://github.com/matrix-org/matrix-doc/issues, whose description should list the metadata as per below. +- 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. - - Iterating on the proposal and getting consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. -- Once the proposal has consensus and passed review, you **must** show an implementation to prove that it works well in practice, before before a spec PR will be accepted. Iterate on the proposal if needed. + - Iterating on the proposal and gathering consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. +- Once the proposal has sufficient consensus and passed review, you **must** show an implementation to prove that it works well in practice, before before a spec PR will be accepted. Iterate on the proposal if needed. - Finally, please make a new spec PR which includes the proposed changes against https://github.com/matrix-org/matrix-doc/tree/master/specification. This will then be reviewed and hopefully merged! 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 `_. From 07bf61b33b00a87ee25069e722f11d90bb8af1a0 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 May 2018 22:22:09 +0100 Subject: [PATCH 19/40] more tweaks --- specification/proposals_intro.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index e1024e575..878faaa9e 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -10,7 +10,7 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: - Please use Google Docs, or an equivalent system capable of collaborative editing, with versioned history and threaded comments. - 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 trade-offs. + - 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. - 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. @@ -19,6 +19,8 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: - Once the proposal has sufficient consensus and passed review, you **must** show an implementation to prove that it works well in practice, before before a spec PR will be accepted. Iterate on the proposal if needed. - Finally, please make a new spec PR which includes the proposed changes against https://github.com/matrix-org/matrix-doc/tree/master/specification. This will then be reviewed and hopefully merged! +Final decisions on review are made by the +matrix:matrix.org community (i.e. the core team), acting on behalf of the whole Matrix community. + 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 `_. :: From 755c9473fb3b7d3341739eb50d4af0f954b4c90a Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 May 2018 22:27:43 +0100 Subject: [PATCH 20/40] more tweaks --- specification/proposals_intro.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 878faaa9e..b8cad3625 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -16,8 +16,8 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: - 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. - Iterating on the proposal and gathering consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. -- Once the proposal has sufficient consensus and passed review, you **must** show an implementation to prove that it works well in practice, before before a spec PR will be accepted. Iterate on the proposal if needed. -- Finally, please make a new spec PR which includes the proposed changes against https://github.com/matrix-org/matrix-doc/tree/master/specification. This will then be reviewed and hopefully merged! +- 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! Final decisions on review are made by the +matrix:matrix.org community (i.e. the core team), acting on behalf of the whole Matrix community. From 714767c95a99cc7929266d402ec56460564a4466 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 May 2018 22:32:00 +0100 Subject: [PATCH 21/40] explain proposal neutrality --- specification/proposals_intro.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index b8cad3625..ab1e4027f 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -21,6 +21,10 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: Final decisions on review are made by the +matrix:matrix.org community (i.e. the core team), 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. + +The directions above are intended to be short, simple and pragmatic - although a full governance document for the Matrix core team will follow in due course. + 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 `_. :: From 29348c61906a688ed9573081e7f7e807a1254342 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 May 2018 22:35:53 +0100 Subject: [PATCH 22/40] improve wording --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index ab1e4027f..aaae74862 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -23,7 +23,7 @@ Final decisions on review are made by the +matrix:matrix.org community (i.e. the 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. -The directions above are intended to be short, simple and pragmatic - although a full governance document for the Matrix core team will follow in due course. +The directions above are not intended to be exhaustive but simple and pragmatic. A full governance document for the Matrix core team will follow in due course. 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 `_. From e27f674fb95e0162d9b96e269e2d5b4aee4adcfa Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 May 2018 23:00:54 +0100 Subject: [PATCH 23/40] incept dates --- specification/proposals_intro.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index aaae74862..c865f6afb 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -21,7 +21,7 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: Final decisions on review are made by the +matrix:matrix.org community (i.e. the core team), 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. +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. The directions above are not intended to be exhaustive but simple and pragmatic. A full governance document for the Matrix core team will follow in due course. @@ -101,6 +101,7 @@ 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 @!) From f1cc26dfd7f266363bcf8f2b32ec8a375ca12225 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 15 May 2018 11:59:34 +0100 Subject: [PATCH 24/40] sort output by Created date per-table --- scripts/proposals.py | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 0b0717d95..1e556ccba 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -43,7 +43,6 @@ issues = {} for label in labels: issues[label] = getbylabel(label) - print(issues) text_file = open("../specification/proposals.rst", "w") @@ -66,14 +65,10 @@ for label in labels: text_file.write(" - PRs\n") for item in issues[label]: - # 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, find local field, otherwise Github - created = re.search('^Date: (.+?)\n', str(item['body']), flags=re.MULTILINE) + # 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: @@ -81,17 +76,28 @@ for label in labels: 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') - text_file.write(" - " + created + "\n") + 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") From 3cef79f31d92b479b8fa3a0aa0071d4974a4029a Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 15 May 2018 12:09:35 +0100 Subject: [PATCH 25/40] sublist formatting --- specification/proposals_intro.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index c865f6afb..3fc7470e5 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -7,15 +7,19 @@ 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 and threaded comments. - 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. + - 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. - Iterating on the proposal and gathering consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. + - 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! From 3b736388ce82736ee817ff053237c65bc6be281b Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 May 2018 14:17:30 +0100 Subject: [PATCH 26/40] clarify governance --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 3fc7470e5..fd692e526 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -27,7 +27,7 @@ Final decisions on review are made by the +matrix:matrix.org community (i.e. the 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. -The directions above are not intended to be exhaustive but simple and pragmatic. A full governance document for the Matrix core team will follow in due course. +The above directions are intended to be simple and pragmatic rather than exhaustive, and aim to provide guidelinnes 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 that allows. 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 `_. From 42fd3f34e4daf8edcde68106f285e34ee0f9cb6f Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 May 2018 14:46:08 +0100 Subject: [PATCH 27/40] shift stuff from contributing.rst to the new proposals page --- CONTRIBUTING.rst | 43 +++++-------------------------- specification/proposals_intro.rst | 4 +-- 2 files changed, 9 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6f17afe66..2a7416b17 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/specification/proposals_intro.rst b/specification/proposals_intro.rst index fd692e526..e1c467caf 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -21,9 +21,9 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: - Iterating on the proposal and gathering consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. - 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! +- 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:matrix.org community (i.e. the core team), acting on behalf of the whole Matrix community. +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. From 3e10a5a24a81180c89aa411c0c60db22f2850bf0 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 May 2018 15:02:35 +0100 Subject: [PATCH 28/40] enter #matrix-spec:matrix.org --- specification/proposals_intro.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index e1c467caf..019d8eabc 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -18,6 +18,7 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: - 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 architecture. - Iterating on the proposal and gathering consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. - 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. From 8096bf0039df0c7711d5c528ec144ee6e396d5de Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 May 2018 15:07:47 +0100 Subject: [PATCH 29/40] perms and apostrophes --- specification/proposals_intro.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 019d8eabc..35d0adbf5 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -8,7 +8,7 @@ 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 and threaded comments. + - Please use Google Docs, or an equivalent system capable of collaborative editing, with versioned history and threaded comments. 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. @@ -99,7 +99,7 @@ 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 issue's description 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. +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: From 4cdb4f105cfe4ad247977b7a7761b7947c8ceccc Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 May 2018 15:11:51 +0100 Subject: [PATCH 30/40] clarify architecture --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 35d0adbf5..fb72836ce 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -18,7 +18,7 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: - 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 architecture. + - 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. - Iterating on the proposal and gathering consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. - 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. From d338f189278b398da6cc185a73ab8051abc7c5ce Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 15 May 2018 15:22:03 +0100 Subject: [PATCH 31/40] handle EOF gracefully when searching for Authors and PRs --- scripts/proposals.py | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 1e556ccba..e4c65daac 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -1,9 +1,5 @@ # proposals.py: generate an RST file (proposals.rst) from queries to github.com/matrix.org/matrix-doc/issues. # v0.0.1 -# todo: -# use status labels to create separate sections. -# include all fields discussed at https://docs.google.com/document/d/1wLln7da12l0H5YgAh5xM2TVE7VsTjXzhEwVh3sRBMCk/edit# -# format, probably as tables import requests import re @@ -114,7 +110,7 @@ for label in labels: text_file.write("\n") # author list, if missing just use Github issue creator - author = re.search('^Author: (.+?)\n', str(item['body']), flags=re.MULTILINE) + author = re.search('^Author: (.+?)$', str(item['body']), flags=re.MULTILINE) if author is not None: author_list_formatted = set() author_list = author.group(1) @@ -136,7 +132,7 @@ for label in labels: text_file.write(" - " + str(shepherd) + "\n") # PRs - pr_list = re.search('PRs: (.+?)\n', str(item['body'])) + pr_list = re.search('PRs: (.+?)$', str(item['body'])) if pr_list is not None: pr_list_formatted = set() pr_list = pr_list.group(1) From 4d59abebf020d56e97594825b5608edaa77056dd Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 15 May 2018 15:33:39 +0100 Subject: [PATCH 32/40] handle PR links from GitHub --- scripts/proposals.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index e4c65daac..939641433 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -152,6 +152,6 @@ 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) + text_file.write("\n.. _PR" + pr + ": https://github.com/matrix-org/matrix-doc/pull/" + pr.replace('#', '')) text_file.close() From 10a8cb3f67db4ed99e7e5ffffeb664f5bccc1c97 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 May 2018 15:44:40 +0100 Subject: [PATCH 33/40] put handwavey timings on state transitions --- specification/proposals_intro.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index fb72836ce..a174ae6c8 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -83,12 +83,12 @@ Proposal WIP A proposal document which is still work-in-progress 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 is being used in the wild but hasn't yet been 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 is not responsive +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 =========================== ======================================================= From 4c0743ef65f17ae14e9ba50734c0399bde375c1e Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 May 2018 15:47:34 +0100 Subject: [PATCH 34/40] fix wording --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index a174ae6c8..34e6c58ed 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -28,7 +28,7 @@ Final decisions on review are made by the Matrix core team (+matrix:matrix.org), 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. -The above directions are intended to be simple and pragmatic rather than exhaustive, and aim to provide guidelinnes 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 that allows. +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 `_. From 73b28612ec087633f08ec5ab3d5c7083e593da4e Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 15 May 2018 16:07:55 +0100 Subject: [PATCH 35/40] updates from feedback on pull --- scripts/proposals.py | 2 +- specification/proposals_intro.rst | 118 ++++++++++++++++++++++-------- 2 files changed, 89 insertions(+), 31 deletions(-) diff --git a/scripts/proposals.py b/scripts/proposals.py index 939641433..8b2107ac3 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -124,7 +124,7 @@ for label in labels: text_file.write(" - `" + str(author) + "`_") text_file.write("\n") - # shepherd (currnely only one) + # shepherd (currently only one) shepherd = re.search('Shepherd: (.+?)\n', str(item['body'])) if shepherd is not None: authors.add(shepherd.group(1).strip()) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 34e6c58ed..97b1ea22c 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -8,29 +8,75 @@ 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 and threaded comments. 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. - -- 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. - - Iterating on the proposal and gathering consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. + - Please use Google Docs, or an equivalent system capable of collaborative + editing, with versioned history and threaded comments. 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. + +- 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. + - Iterating on the proposal and gathering consensus can sometimes be + time-consuming; an impartial 'shepherd' can be assigned to help guide the + proposal through this process. -- 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. - -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 `_. +- 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. + +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 +`_. :: @@ -97,17 +143,29 @@ Rejected A proposal which is not going to be incorporated int Proposal Tracking ----------------- -This is a living document generated from the list of proposals at `matrix-doc/issues `_ on GitHub. +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. +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! +- 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. +- 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. +- 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. From 84524df7830faadca24d9d8462ce03216467afc8 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 May 2018 17:38:33 +0100 Subject: [PATCH 36/40] spell out requirements for doc editing --- specification/proposals_intro.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 97b1ea22c..dae5ac996 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -9,8 +9,9 @@ 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 and threaded comments. Please ensure the - document is world-commentable or -editable. + 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. From 4d3c4225b21e8e3b4d4d883b45570515a6776d19 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Wed, 16 May 2018 11:12:57 +0100 Subject: [PATCH 37/40] include proposal template link --- specification/proposals_intro.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index dae5ac996..47393fa6d 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -24,6 +24,9 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: - 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 From 8440179ecfc5ce9d052fc3c8cfbca6256da0e4ad Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Thu, 17 May 2018 18:21:39 +0100 Subject: [PATCH 38/40] clarify shepherds and clarify 'greater benefit' as per https://github.com/matrix-org/matrix-doc/pull/1240#discussion_r188459957 --- specification/proposals_intro.rst | 41 ++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 47393fa6d..ce5773376 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -45,9 +45,14 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: trying to run matrix apps (clients & servers); #matrix-architecture:matrix.org is for cross-cutting discussion of Matrix's architectural design. - - Iterating on the proposal and gathering consensus can sometimes be - time-consuming; an impartial 'shepherd' can be assigned to help guide the - proposal through this process. + - 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 @@ -69,6 +74,36 @@ rather than benefiting or privileging any single player or subset of players 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 From 38adc7df06743af333fd24aa04408e13aad9eff4 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Thu, 17 May 2018 18:25:13 +0100 Subject: [PATCH 39/40] latest generated proposals --- specification/proposals.rst | 618 +++++++++++++++++++++++++++++- specification/proposals_intro.rst | 30 +- 2 files changed, 629 insertions(+), 19 deletions(-) diff --git a/specification/proposals.rst b/specification/proposals.rst index 5a1f02c07..da9d277ff 100644 --- a/specification/proposals.rst +++ b/specification/proposals.rst @@ -1,5 +1,615 @@ -.. contents:: Table of Contents -.. sectnum:: +Tables of Tracked Proposals +--------------------------- -The Proposals List ------------------- +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 index ce5773376..fecfc2f99 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -84,25 +84,25 @@ 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 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 +* 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 From 9873a2a0ac40dfcdce4bac71f61d849f2172570e Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Thu, 17 May 2018 18:33:12 +0100 Subject: [PATCH 40/40] link from the spec intro page --- specification/intro.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/specification/intro.rst b/specification/intro.rst index 064f9d178..ad5452484 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 ------------