Spec Proposals page on matrix.org #1240
Conversation
specification/proposals_intro.rst
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
"as rapidly as that allows" is a bit awkward in wording. Don't mean to bikeshed, but I was skimming through this and had github open anyway, so I thought I'd point out any areas that confused me a bit.
specification/proposals_intro.rst
Outdated
| 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 |
There was a problem hiding this comment.
Some information somewhere on who gets to decide these kinds of states would be nice, and when they take effect. Not only the Abandoned state, but the other's as well.
There was a problem hiding this comment.
i'm worried that this could spiral into a massive debate over the decision making progress, which i'm trying to avoid getting sucked into until the project is looking more healthy. for now, those with commit access to the repo get to triage the issues. i'll add something about timings, for the time-based transitions.
specification/proposals_intro.rst
Outdated
|
|
||
| - 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. |
There was a problem hiding this comment.
please could we aim for wrapping rst at 80 chars?
(a) it makes it easier to read the source
(b) it makes review easier as you can be more specific in your comments
(c) we require it for other parts of the spec and it would be nice to be consistent/set a good example
There was a problem hiding this comment.
Good idea, I'll update.
scripts/proposals.py
Outdated
| text_file.write(" - `" + str(author) + "`_") | ||
| text_file.write("\n") | ||
|
|
||
| # shepherd (currnely only one) |
specification/proposals_intro.rst
Outdated
|
|
||
| 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. |
|
If I ever get around to putting to writing up some of the spec proposals I have floating around in my head, would etherpad with this plugin be okay? If not, what's missing still? The reliance on google docs for spec proposals is an actual barrier to me contributing, and I'm trying to find ways around it. |
|
I've pushed some more requirements for the doc proposal editor tool:
Looks like etherpad + comments plugin might check all of those apart from suggestions/track-changes and possibly good mobile support... although at least in etherpad /every/ edit is effectively track-changes'd. But being able to review/comment/accept/reject suggestions has proved very useful on prior spec work. In the end, it's up to the author - if it's a pretty simple proposal which doesn't expect much iteration or collaboration etherpad might be fine. But we'd definitely continue to recommend Google Docs for now as the preferred default (unless someone finds a better soln!) |
specification/proposals_intro.rst
Outdated
| 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** |
There was a problem hiding this comment.
sufficient consensus
I believe this needs to be defined with objective metrics, even if simple at first, as it is currently up to the interpretation which can widly differ from person to person
There was a problem hiding this comment.
probably, but that's a bigger governance question, which these guidelines aren't trying to solve - the point here is to unblock spec contribution rather than change the governance problem of the project right now. for now, 'sufficient consensus' means that everyone on the core team who's reviewed the proposal approves it and nobody vetos it. In future I'd expect the core team to include folks from across the community.
specification/proposals_intro.rst
Outdated
| 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 |
There was a problem hiding this comment.
works well
I believe this needs to be defined with objective metrics, even if simple at first,as it is currently up to the interpretation which can widely differ from person to person.
There was a problem hiding this comment.
That is like asking what quality is. For now, if the implementation demonstrates that the proposed spec change solves the problem in a manner that is fit for purpose, then that's good enough to warrant spending the time on a spec against the PR.
There was a problem hiding this comment.
then wouldn't to prove that it works in practice be enough? well might be misleading here.
There was a problem hiding this comment.
that seems pedantic at best. any proposal can be implemented. the question is whether the implementation demonstrates that the resulting feature or solution is fit for purpose. defining what that means is left to the specific proposal and the problem it seeks to solve.
| guidelines. | ||
|
|
||
| Final decisions on review are made by the Matrix core team | ||
| (+matrix:matrix.org), acting on behalf of the whole Matrix community. |
There was a problem hiding this comment.
Why not elected entities from the community that contributed implementations?
There was a problem hiding this comment.
Just because someone happens to have gone and written a Matrix implementation doesn't mean they are able to play nice with others, make constructive contributions to spec development, or that they should automatically get sign-off on what the protocol looks like.
As we try to rapidly converge on a long overdue stable release (0.1, 1.0 or whatever) of Matrix we need more agility and speed than ever before - especially in terms of disruptive changes like changing Matrix's whole identity model by switching ID formats to be public keys, reworking Federation to address problems like state resets, changing/adding semantics to support GDPR, fixing scalability problems with features like membership lazyloading etc. Anything that slows that process down is a bad thing, and just because some folks have chosen to implement an unstable and pre-release API such as the server-server API is not a good reason to slow down development of that API or prematurely switch to design by a committee selected somehow from the wider community.
Instead, the plan is to get to a stable release as rapidly as we can, gathering as much input and assistance as we can from the wider community with stuff like the new spec proposal process, and to finish the process we started back in 2013/2014. We are effectively feature frozen for new end-user facing features (ignoring GDPR) since the end of 2017, so it seems plausible to get the current features stable enough that we can declare it out of beta. Then, once we actually have a protocol and reference implementations which are fit for purpose, it seems like a perfect opportunity to make the governance model more inclusive across the whole ecosystem. The process for that would be to renew the core team from participants from across the whole community, with participation in that team likely being by unanimous agreement of those already in it. It would try to span all stakeholders, be they users, client developers, bridge developers, bot developers, server developers, spec contributors, etc.
I appreciate this is a U-turn from when we spoke a few months ago and I said we'd try to prioritise governance work over spec and implementation work - but having sketched out a governance doc and worked on it a bit, I've come to realise that the risk from investing time in doing so and the risk from handling the disruption as selfish/pedantic/misguided players try to grab the steering wheel is a massive threat to the success of the project at this point in its life, relative to the benefits it could bring. And it's certainly not something that one should be bullied into doing.
So, instead, the focus continues to be on getting to a stable release of the spec & reference implementations as rapidly as we can, and I ask that the community continues to trust the core team to try to steer in the right direction and act for the good of the whole ecosystem - just as we've tried to do since Day 1. Hopefully the new spec process here will also make it much easier for the wider community to contribute and participate, even if they don't have right to dictate what goes into the final spec. Meanwhile, once we are out of these growing pains (i.e. we have a protocol which isn't vulnerable to malicious attacks, or servers which take 10s to send a message, or clients which take gigabytes of RAM), it will be a no-brainer to widen control to incorporate the wider 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, |
There was a problem hiding this comment.
act to the greater benefit of the entire Matrix ecosystem
That's highly subjective. Objective metrics, even if simple at first, should be used instead I believe.
There was a problem hiding this comment.
I'm not able to tell you which since I'm not the one who wrote the text. What I know for sure is that the greater benefit of the Matrix ecosystem is radically different between you and me per example, and it certainly is different from jzk, or from other independent Matrix developers.
Defining what the "Matrix ecosystem" and "greater benefit" are supposed to be would be appropriate here, so everyone knows if their view align and if there is a point spending time writing proposals.
There was a problem hiding this comment.
I'm not able to tell you which since I'm not the one who wrote the text.
This is pretty much the definition of being irritating to work with, from my perspective, and is the reason why I would never want this sort of behaviour in the core team. If you criticise something then you should be able to make a constructive proposal rather than saying "because i didn't write it i can't make a suggestion on how to improve it".
Defining what the "Matrix ecosystem" and "greater benefit" are supposed to be would be appropriate here, so everyone knows if their view align and if there is a point spending time writing proposals.
The Matrix ecosystem is anyone who uses the Matrix protocol (https://matrix.org/docs/spec). 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 core team 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
However, this is already becoming a bikeshed of governance which is precisely what I was trying to avoid - instead, at this point, contributors are expected to assume good faith and trust the core team, which the project owes its existence and (relative) health to. And if you can't do that, then please locate your nearest exit rather than screwing it up for everyone else.
There was a problem hiding this comment.
You seem to see ill-intend everywhere. The sentence is just not clear to me. It might be clear to the person writing the text, or to people who are native English speakers, but might not be to everyone. That kind of lack of clarity caused issues in the past, so I'm pointing out those words or notions which might not be obvious to everyone else.
You don't have to clarify it. you can just say "it's clear enough for me" or "we'll clarify later". Being mean is really unnecessary here.
| (+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 |
There was a problem hiding this comment.
By self-appointing themselves as final judge on proposals, the Matrix core team is already privileging itself.
There was a problem hiding this comment.
yup, the core team is in a privileged position having created the thing and having self-appointed itself responsible for steering it to a stable release. if you don't like this, then i'd suggest finding a different project which better fits your expectations, or wait until the governance is broadened.
There was a problem hiding this comment.
It's not a matter of liking it, but rather go into more details how you plan on preventing any bias and ensuring that that privilege is not misused in practice. Like any other bootstrap, the creator is always privileged at the start. The question is what is done to remain fair as far as possible and convince other that there are ways to prevent abuse of that privilege.
So to re-iterate: you have final judgment on proposal, and you are in a privileged position: what process (if any) will you put in place to ensure "rather than benefiting or privileging any single player or subset of players" is enforced on the core team too?
There was a problem hiding this comment.
Not pissing off the entire community would hopefully be enough motivation for them to not abuse or misuse their position.
There was a problem hiding this comment.
^ This, and from a game theoretic perspective we are incentivised to make Matrix as successful as possible for all participants, in order to maximise its network effects and make it most useful and valuable for any given stakeholder. Given this is the whole point and promise of Matrix, we would be idiots to do anything to jeopardise the network for our own selfish benefit.
| optimal solution. | ||
| - A good place to ask for feedback on a specific proposal is | ||
| `#matrix-spec:matrix.org <https://matrix.to/#/#matrix-spec:matrix.org>`_. | ||
| However, authors/shepherds are welcome to use an alternative room if they |
There was a problem hiding this comment.
The notion of shepherds should be explained, at least briefly, as it hints to a very important cultural setting: a proposal is not about one's idea which is put against other proposals that would try to solve the same problem. Instead, authors/sheperds are supposed to act as some neutral actor (regardless of their own believes) and bring forth a proposal which takes into account everyone's opinion. This is a very crucial notion which is not known or recognized by everyone.
There was a problem hiding this comment.
fair enough. the idea of proposals is to be collaborative rather than competitive, and we should make that clear.
| - 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 |
There was a problem hiding this comment.
Notion of shepherd should be explained (see previous comment on the matter)
Render commas between enum values.
An implementation/spec-PR of the very rough proposal at #1233