Collaboration and governance model

[cschreib]

I have seen multiple open-source projects die a slow death as their owner stops actively caring for them, not even merging pull requests from external contributors. I would like for snitch not to follow this path, and I think the only way to protect against this is to open up the project to have more than one maintainer (i.e., currently that's me). This needs to be done in a way that preserves quality (e.g., following a roadmap, coding guidelines, testing strategy, caring for the API, benchmarks, etc.) and security (i.e., prevent malicious commits from making it into a public branch).

This issue is created to discuss how this can be done in practice, and gather opinions from users and would-be maintainers.

[cschreib]

My first thought was to reach out to past contributors who have shown interest in the project and successfully merged a PR (@tocic, @willwray), and invite them to become formal collaborators on this repository. It seems however that GitHub personal projects (which snitch is) have very coarse grained permissions. The project would need to be owned by an organisation (e.g., "snitch-org") instead of an individual (me). This may be a necessary first step.

What I had in mind goes like this:

• A brand new contributor must use the fork + PR model, which has been working well. This allows them to build up trust in a very controlled environment, since only an established contributor or maintainer can approve their changes after review. I expect this is where most people will stop, as they don't want to get involved any deeper. We need to keep supporting this light-touch level of involvement and contribution.
• Once basic trust is established, the contributor can be invited (or can ask to be invited) to become an "established contributor" (name TBD). An established contributor gains the right to merge into any branch of the repository, except main. Since contributors have freedom to create any branch, they can decide on any branching model that works best for them. The only line in the sand is that main is off limits. One idea could be that we could introduce a new dev branch, which becomes the new bleeding edge "head", and where contributors can approve PR from others without requiring approval from maintainers. Any PR still requires at least one approval from another contributor (or maintainer) before merging, so there is a first level of code review going on there. Then dev gets PRed into main from time-to-time, or when a release is needed.
• After a contributor has demonstrated enough mastery of the project and earned full trust, they can become a maintainer. Maintainers can approve PRs into main, create releases, invite contributors, etc.

There's probably a lot to sort out, in particular around demoting (removing a contributor or maintainer), etc. I also don't particularly fancy the added overhead of a dev branch, and handling PRs from dev to main that have accumulated 10k LOC to review... So this probably needs a lot of thoughts. Until someone else than me attains the rank of "maintainer", the situation remains mostly the same as today: if I go under a bus, the project is stuck. But at least contributors can organize and create a new_main or something, or officially declare dev as the new main (but then what about releases?).

I'd be happy to read about other people's experience in contributing to open-source projects, and examples of what has worked for others.

[tocic]

Yep, I agree with your collaboration model and motivation to introduce it, as well as I prefer trunk-based development to dev/release branching. Unfortunately, I only have the experience of either having full control over the repo (work and pet projects) or leveraging the fork+PR model (open source), so I can't give any useful practical advice here. Perhaps the CODEOWNERS mechanic would be useful for separating responsibilities.

[cschreib]

I would prefer the trunk-based approach as well; this is what we use at work too. If I decide to ditch the idea of a dev branch, and allow every other maintainers to merge PRs into main (possibly with some filters via the CODEOWNERS file), there are some caveats I need to either solve or get comfortable with.

As project admin, I currently have the privilege to merge my own PRs without requiring the review of another maintainer. I don't think this is a healthy privilege to preserve going forward, but until there is an active pool of other maintainers available, I don't really have a choice. I think I can set things up so that I alone retain that privilege (for a time), while other maintainers must have approval from one other maintainer before they can merge their own PRs. This will impose a minimum level of quality control over what gets merged, however it means that they can possibly do the following without involving me at all:

• If they get approval from another maintainer, they can merge each other's PRs.
• They can approve and merge a PR from any other external contributor.

Allowing this to happen is the whole point of this exercise, but it requires a fair bit of trust. I don't know how to decide that someone is trustworthy enough, at this stage (no offense!). I suppose there's always the possibility to revert unwanted change, if an a posteriori review flags up issues, so maybe I'm overthinking it.

[cschreib]

A useful resource: https://opensource.guide/leadership-and-governance/. They describe various contribution models, one of which is the "liberal contribution" model, with a real world example from Node.js. It is a bit scary, because it is so open and trusting, but it does acknowledge one thing that rings true to me: there's probably more value in getting more contributors than there is in attempting to preserve quality by locking things down. Food for thoughts.

[cschreib]

snitch is now part of the "snitch-org" organization: https://github.com/snitch-org/snitch. Links to https://github.com/cschreib/snitch will automatically redirect, including remote URLs configured in local git repositories. Update at your convenience; the old URL will always remain usable.

The organization currently contains two "teams", as inspired by this article (just with different names):

• Maintainers. Every member of the organization is part of this team. As a maintainer, you are able to review and merge PRs, open and close issues. This essentially gives you full write access to the repository. Being part of this team only involves one responsibility: adhering to the code of conduct (to be added). It comes with no responsibility to commit time or effort; however much you can give is enough. As a maintainer, you are able (if you wish) to steer the project into new directions, propose features, refactoring, influence the roadmap, etc., and act on it. You have veto right on any PR. You can invite other maintainers to the team.
• Mediators. Only some maintainers are part of this team. As a mediator, you are responsible for resolving disputes, technical or otherwise. Hopefully this is never needed.

At present I am the only member, and I am part of both teams. I am also admin of the org, which means I am able to bypass certain restrictions. These are the same privileges I enjoyed so far by being the sole owner of the repo. In particular, I am able to push directly to the main branch (which I will never do unless it's an emergency), and merge my PRs without approval from another maintainer (which I will do until the pool of maintainers is big enough).

NB: this does not change anything for external contributors. Everyone is still able to fork and create a PR to suggest changes, regardless of whether they are part of the org or not.

Next step: add a code of conduct and a governance document. Then invite some maintainers!

[cschreib]

#133 (and #134) added a code of conduct and an enhanced documentation for contribution. These two documents define the governance model, following the above.

[cschreib]

I think this is ready to go; closing. Feel free to comment here for any feedback, or in the discussions.