Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

MSC4073: Shepherd teams #4073

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

MSC4073: Shepherd teams #4073

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fd0db19
MSC: Shepherd teams
joepie91 Nov 7, 2023
548f331
Fix formatting
joepie91 Nov 7, 2023
97a22f2
Make rejection process explicit
joepie91 Nov 7, 2023
52bcf9e
Clarify authorship responsibility
joepie91 Nov 7, 2023
06f98e1
Define SCT tasks
joepie91 Nov 7, 2023
4c4ad7d
Define transition strategy
joepie91 Nov 7, 2023
4f7dd10
Explicitly call out implementer review
joepie91 Nov 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions proposals/4073-shepherd-teams.md
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Process-wise, I think it's actually best if we sit on this and think about it for a while (ironically). The MSC is largely written in response to recent events, and we should be cognisant that those events may be clouding judgement. Similarly, we should not rush into decisions when it comes to process: they need careful thought and consideration, even if appearing simple on the surface.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MSC is largely written in response to recent events

That is not quite accurate; none of these issues are new, and all of them have been brought up in a more informal manner many times, including suggestions to have the SCT do less. What has changed recently, are two things:

  1. The Foundation is now showing itself more receptive towards governance changes than before, and
  2. The situation has worsened to a degree that the Foundation itself expresses public concern about a lack of third-party contributions, and there is a lot of unrest in the broader Matrix community about what this means for the future of Matrix, for which there need to be concrete answers.

So rather than this being a sudden novel idea, it's an idea that has been floating around in various form for quite some time already, and has already proven its worth in another community (which has actually partly modeled its spec process on that of Matrix, to my knowledge), and it is now at a point where concrete solutions need to start appearing, so as to not to lose the remaining trust of the community.

Similarly, we should not rush into decisions when it comes to process: they need careful thought and consideration, even if appearing simple on the surface.

Of course, careful consideration is important, that is part of why I submitted this as an MSC rather than trying to backchannel it. But this does not need to translate into a long approval process in terms of time, and it's not clear to me in what way this proposal would be expected improve by letting it sit, in and of itself.

In this consideration, given the circumstances and the worsening community trust issues, I also think it is important to ask: what possible worst-case scenarios are there for the outcome of this proposal, that are worse than the outcome of not changing the process?

Because governance change proposals do not need to be perfect to be useful, they just need to be an improvement over what we currently have, so if it turns out that something was overlooked, this can always be rectified down the line (especially since the SCT still retains the power to intervene if really necessary).

Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# MSC4073: Shepherd teams

Matrix currently has significant problems with its specification change process. There are several common complaints from contributors:

1. "Nobody responds to my MSC"
2. "It takes forever to get an MSC passed"
3. "It's not clear what the status of my MSC is, or what I am supposed to do next"

From conversations with various Spec Core Team (SCT) members, all of these have (at least) one identical root cause: the SCT does not have enough bandwidth to manage, review, and approve all of the submitted MSCs. This causes communication to become minimal, and for MSCs considered "less critical" to languish and eventually become abandoned by their authors, who often give up on Matrix protocol development entirely due to their bad experiences. The SCT cannot be bypassed, because its final approval is required for any MSC to be considered mergeable.

## The current process

In the current MSC process, it is the responsibility of the SCT to manage the discussion and direction of every MSC, and ultimately give its final approval before a merge is possible. A shepherd may be assigned to guide the MSC process independently of the SCT - but they ultimately only serve the role of a *guide*, and do not hold any authority over the final decision to merge or reject. A shepherd is also not required, and frequently is not assigned. Altogether, this often leaves an impression with contributors of "appealing to a disinterested SCT".

## Proposal

This MSC aims to solve these problems, or at least make a first significant step towards doing so, by changing the scope of responsibility of the SCT. It introduces the concept of a "shepherd *team*", and makes them primarily responsible for the MSC's progress. This team is assigned on a *per-MSC* basis, and it is modelled after [the "shepherd teams"](https://github.com/NixOS/rfcs/blob/master/rfcs/0036-rfc-process-team-amendment.md) in [the NixOS RFC process](https://github.com/NixOS/rfcs#readme).

The new process will work as follows:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are some cases where an MSC is fairly trivial, and everyone just agrees that it should be done (MSC3828 might be a good example of this). For such MSCs, creating a shepherd team for it might be unnecessary administrative overhead, and I wonder if it might be worthwhile to keep a "shortcut" of having the SCT accept the MSC. I'm not sure if it happens often enough, though.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a fair point; I'm not opposed to adding such a shortcut, but I do think that it should be a well-defined one, such that that path is only taken when there's reasonable certainty that it can be passed quickly. My main concern is that if there isn't such a defined threshold, it can become appealing for SCT members to take on more work than they can realistically handle, out of excitement/optimism.

I'm thinking something along the lines of:

If the SCT believes that the proposal can be passed within 3 weeks, then the SCT itself may function as the shepherd team for that MSC, skipping the shepherd assignment process. If, against expectations, after 3 weeks the proposal has not yet been merged, the MSC is no longer eligible for this accelerated treatment, and the normal shepherd assignment process must be followed belatedly.

... but I'm open to other suggestions as well.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally, I'm not a fan of making too many rules unless necessary. If we do want to add this shortcut, I'd be more in favour of either making it a guideline rather than a rule ("if the SCT hasn't managed to get their act together within 3 weeks, then they should really consider assigning it to a shepherd team"), or leaving it open and then fixing any bugs if they occur later on.


1. Community members submit nominations for shepherds, in the MSC's discussion thread. The nominees should be people who are closely familiar with the subject matter of the MSC, but not be the author. Community members may also nominate themselves.
2. The SCT selects multiple nominees to become the "shepherd team"; ideally 3 or 4 people.
- The SCT may likewise nominate candidates (eg. if there are too few nominees), but should leave the opportunity for other community members to object to the SCT's nominations.
- No more than half of the shepherds may be SCT members.
- The shepherd selection should avoid conflicts of interest, and be a diverse representation of perspectives on the topic (within the boundaries of the Code of Conduct).
3. The shepherd team will be responsible for guiding the discussion on the proposal. This discussion should incrementally improve the proposal until outstanding concerns have been resolved. They may request administrative assistance from the SCT if eg. moderator intervention is required.
4. Once the shepherd team feels that all concerns have been resolved satisfactorily, and that there is no meaningul refinement left to be done, they can carry out a final technical review, and call FCP (Final Comment Period).
- This requires unanimous agreement from all shepherds.
- The SCT must be informed immediately by the shepherds when the FCP starts, so that the SCT can make a public 'last call' for feedback.
- The FCP process itself remains as it was before.
5. If FCP passes without objection, the shepherds declare the MSC accepted, and notify the SCT. The SCT will then merge the proposal.

Some of the most important takeaways from this:

- The SCT is no longer the final reviewer and approver; this responsibility is delegated to the shepherd team for that MSC.
- The shepherd team is trusted to ensure that:
1. the proposal represents diverse interests, and
2. the proposal does not conflict with other proposals, coordinating with shepherds for other MSCs if necessary.
- The SCT no longer concerns itself with the *content* of MSCs, but only with supervising the process.
- The SCT may still intervene where necessary to resolve administrative disputes, or replace shepherds if they become unavailable.

This is a significant step towards a more community-driven protocol, by putting more of the specification process in the hands of community members, and more crucially, it frees up significant capacity from the SCT.

This proposal does not currently encompass the question of "who writes the final specification text?" - that is left unchanged from the current situation, and may be clarified or changed in a separate MSC.

## Anticipated outcomes

Primarily, this should unblock the many MSCs that some community members feel strongly about, but that the SCT has not had the capacity to advance, eg. because it accommodates a relatively specialized need. This should overall significantly improve on the throughput and responsiveness of the MSC process, much like it has already done for NixOS.

Indirectly, this would improve community trust and engagement regarding protocol development, because contributors would no longer feel ignored, and they can continue building additional work on top of previous work - where that previously would have been blocked on a 'stuck' MSC, and the uncertainty of it ever getting merged.

Another anticipated indirect effect is increased transparency in the specification design process; it is currently an issue that a lot of specification design happens 'internally', behind closed doors, and this can currently be gotten away with due to every MSC going through a central point of review (the SCT) before merging, where any incompatibilities can be ironed out.

In the 'shepherd team' model, this is no longer possible, as one cannot expect 'internal' and undocumented decisions to be taken into account by other shepherd teams in their final review, and so all such specification development *must* happen out in the open (as is ultimately desirable for an open protocol).

## Security concerns

It is *technically* possible for an organized effort to disrupt the specification by passing something without SCT review. However, this has not been a problem for NixOS at all, and would require compromising the *entire* shepherd team. Additionally, administrative intervention from the SCT remains possible in exceptional cases (like when a shepherd has become unavailable), and this could likewise be applied to such cases.

## Alternative approaches

- __Scaling up the SCT:__ Organizations become more unwieldy as they try to scale up monolithically. Additionally, this requires more full-time commitments than anyone currently seems to be willing and able to fund, and would bring conflict-of-interest concerns with it. This does not seem viable.
- __Doing nothing:__ Increasing amounts of potential contributors are bouncing off Matrix due to the problematic MSC process, and it is well-documented that there are currently very few external contributions. This would likely lead to a slow death of Matrix as an open protocol.
- __Bigger MSC scopes:__ This would reduce the amount of units for the SCT to review and manage, but make changesets so large that the discussion of the implementation details would likely exponentially explode, making the problem worse on another axis.
Loading