GOVERNANCE.md: remove “Community Processes” in favor of “GOVERNANCE.md”

[miri64]

Contribution description

As discussed during the RIOT summit (see @jkarinkl's excellent talk), we need a GOVERNANCE.md document. After we discussed this among maintainers for the past week, we came to the conclusion that it's best to move what is still relevant from our old Community Processes and update it to our current understanding on how the community works. The result is the document introduced here.

Digest week 1: https://forum.riot-os.org/t/moving-from-community-processes-to-governance-md/4433/2

Testing procedure

Read it and if you do not agree with something, voice your opinion.

Issues/PRs references

Requires at least #21066 to be merged for the links to the list of maintainers to work properly. (merged) #21062 would be better, but this still needs some (technical issues solving) love. (now merged as https://www.riot-os.org/maintainers.html)

[riot-ci]

Murdock results

✔️ PASSED

4b956f8 squash! GOVERNANCE.md: remove “Community Processes” in favor of “GOVERNANCE.md”

Success	Failures	Total	Runtime
1	0	1	01m:07s

Artifacts

• Documentation preview

[mguetschow]

Thanks for your work on this! Mostly editorial comments below from reading through the preview (deep link).

[emmanuelsearch]

suggestion: organizations => entities/institutions ?

[miri64]

I used "organizations" throughout the text. Intuitively, I would not know what is meant with “entities” and “institutions”, in my opinion, would exclude, e.g., independent people who just work on third-party funding.

[emmanuelsearch]

I see what you mean, but "organization" also exclude non-affiliated people? What's an organization of 1 ;)
The "balance of power" subtly hinted at here seems fuzzy. How about something like "spread admin responsibilities over the different stakeholders" ?

[miri64]

I am fine with stakeholders. See 15934ea.

PS: It's not just “balance of power” in the ephemeral sense, but also to reduce bus factors.

[miri64]

Squashed but kept co-authorship of all whose suggestions so far have been included.

[miri64]

Also lost in trunctation #21067 (comment):

We currently don't have any appointed moderators for other communication channels, do we? This text makes it sound as if we had (or at least would like to have) them, but doesn't give a hint on what those are.

[…] No, we don't have.

With the chats it usually goes the “IRC way”. People are appointed somewhat on merrit and on how active they are. Since the moderation roles in the chats is, however, a little bit different than on the forum, I don't think there needs to be a moderator appointment procedure for that.

With the few mailing lists remaining, the moderators are mostly sorting out spam, so while similar to forum moderation, I also don't think appointment procedures are necessary here.

A forum moderator, on the other hand, actually can moderate a discussion on the forum, in the traditional sense of the word. They can edit posts, they can split out conversations in new topics and make forum topics a “wiki post” (so something everyone can edit). In that regard, they have much more power and require a certain level of trust from the community.

[jkarinkl]

Nice work @miri64, good setup!

Some general remarks:

Nice that the roles within the community are described. Some descriptions of how one can get into or out of a role are described very general, not specific. On that I would suggest:

• Keep it general if this works/has worked in the past and there were no issues or ambiguities that caused trouble. That gives flexibility to react appropriately when something would arise in the future - and prevents too much bureaucracy ;).
• Make it specific if there were difficulties in the past or if that can be expected in the future on deciding who gets into or out of a certain role. This gives guidance of what procedure to follow so that everyone has a level playing field.
• I've added this in the text when relevant; please add on where you think more or less specific description would be handy.

Do we want to add a contributor ladder?

• This would make the 'career path' of roles within the project clear, including what responsibilies and requirements are given/needed.
• If so, the description of roles in this governance document can be much shorter and there can be a reference to the contributor ladder.
• It is nice to have from an an-boarding perspective, but can also be done/added at a later moment

And last suggestion:

• add a reference to the governance doc in the readme.

[jkarinkl]

Question from my side: can a contributor also actively ask for becoming maintainer? This would make it less of a 'waiting until someone may ask me' and gives some responsibility to a contributor too.

If yes: can there be an addition to the text, stating this possibility and a description of how to do that (how to reach out, to whom etc)?
If no: than don't add :).

(I would advice to describe here how the procedure currently is, so if the procedure is someone is being asked only, than keep it this way. If it has happened before that people reach out by themselves and that is desirable, than change it)

[miri64]

In the past it was very obvious in their behavior if a contributor intended to be a maintainer (reviewing PRs even without the rights to merge and writing issues), but in general there is no precedence of a would-be maintainer outright asking. So I'd say let's keep it as is, but I will put this in my forum summary of the current state of discussion.

[maribu]

Hmm, let's say a contributor would approach a maintainer to also become a maintainer. I would assume that this would then be raised to the other maintainers and discussed pretty much in the same way as if the a maintainer suggested it.

Or would anyone of us reject such a request right away without reaching out to the others?

If not, we could also IMO just document that contributors may reach out to a maintainer of their choice, who will forward this to the other maintainers for consideration.

[miri64]

If not, we could also IMO just document that contributors may reach out to a maintainer of their choice, who will forward this to the other maintainers for consideration.

Question is: is this something we need to put in our governance document, i.e., do we want to make it “law” that this is a way to become a maintainer? This could go into the contribution ladder document @jkarinkl proposed and would probably be a better fit.

[jkarinkl]

I would recommend keeping the governance doc as short as possible, so indeed, add this to the contribution ladder. This part is about being friendly and welcoming to enthusiastic contributors, making it easy to step up if they are capable and willing.

[miri64]

This part is about being friendly and welcoming to enthusiastic contributors, making it easy to step up if they are capable and willing.

So to add or not to add a sentence?

[jkarinkl]

Nice to have a person who can act as tiebreaker!

How exactly is decided who this is? As in: if there is disagreement on a topic, how is decided who the maintainers knowledgeable the area of expertise is, exactly? Can that be described here?

If there is disagreement on who this person is, what can be used as tiebreaker to decide?
(to answer this question it helps to ask yourselves: what did successfully work in the past?)

[miri64]

How exactly is decided who this is? As in: if there is disagreement on a topic, how is decided who the maintainers knowledgeable the area of expertise is, exactly? Can that be described here?

Within the IETF there working groups with one chair are uncommon. So why can't multiple maintainers be the deciders here as well? Rough consensus means that the opinions of experts also should not be disregarded, so this describes exactly this case.

If there is disagreement on who this person is, what can be used as tiebreaker to decide?
(to answer this question it helps to ask yourselves: what did successfully work in the past?)

So far a tiebreaker was not needed, if I remember correctly.

[jkarinkl]

How does this work with decision regarding documentation?
And regarding strategy setting/vision/goals?

Here too: what has worked successfully on (controversial) decisions in documentation in the past, and what procedures lie behind it that can be used for future decision making? And what was successful for taking strategy decisions?

[miri64]

How does this work with decision regarding documentation?

Documentation is typically about something code related, so I'd say the maintainer responsible for the code (after all, they could e.g. also see immediately that the doc is factually incorrect).

And regarding strategy setting/vision/goals?

We have our maintainers / experts there as well (see #21067 (comment) ff). :-)

[jkarinkl]

And a general comment relevant to the underlying governance structure (but not needed to add in the text), is the influence of organizational hierarchy.

The RIOT community consists of many people who are working at organizations/companies/institutes with formal hierarchy, which means there are managers/employers/professors and subordinates/employees/students with a dependency relationship. This may effect the level of freedom an individual community member experiences when sharing an opinion and/or the tacit weighting of an individual's opinion.

These sometimes double roles (hierarchical on organizational level, equal on community level) are handy to keep in mind with decision making processes. It is something we may remind each other of every now and then, so that indeed, as described in this document, no individual dictates decisions and all participants feel equal able to take part and be heard in discussions :).

[miri64]

Thanks for your review @jkarinkl! Some remarks on the non-inline comments:

From #21067 (review)

[…] Some descriptions of how one can get into or out of a role are described very general, not specific. On that I would suggest:

• Keep it general if this works/has worked in the past and there were no issues or ambiguities that caused trouble. That gives flexibility to react appropriately when something would arise in the future - and prevents too much bureaucracy ;).
• Make it specific if there were difficulties in the past or if that can be expected in the future on deciding who gets into or out of a certain role. This gives guidance of what procedure to follow so that everyone has a level playing field.
• I've added this in the text when relevant; please add on where you think more or less specific description would be handy.

(also somewhat in response to @emmanuelsearch's #21067 (comment))

I somewhat had it intentionally somewhat general/fuzzy, since I don't think we currently have very specific rules for these things in place and currently the document describes the status quo. Should we be more specific? If yes, what are the specifics? This is something, I guess we need to decide as a community not just arbitrarily by me. If someone has specific problems that we had in the past that are currently not covered by the document, please point them out and give proposals how to solve them.

Do we want to add a contributor ladder?

• This would make the 'career path' of roles within the project clear, including what responsibilies and requirements are given/needed.

• If so, the description of roles in this governance document can be much shorter and there can be a reference to the contributor ladder.

• It is nice to have from an an-boarding perspective, but can also be done/added at a later moment

I would leave that to a follow-up PR.

• add a reference to the governance doc in the readme.

See 2a3a4fe.

From #21067 (comment)

The RIOT community consists of many people who are working at organizations/companies/institutes with formal hierarchy, which means there are managers/employers/professors and subordinates/employees/students with a dependency relationship. This may effect the level of freedom an individual community member experiences when sharing an opinion and/or the tacit weighting of an individual's opinion.

These sometimes double roles (hierarchical on organizational level, equal on community level) are handy to keep in mind with decision making processes. It is something we may remind each other of every now and then, so that indeed, as described in this document, no individual dictates decisions and all participants feel equal able to take part and be heard in discussions :).

So do you think this should be explicitly mentioned in the GOVERNANCE.md?

[miri64]

For those who missed it: I posted a digest of the current state of discussion and open questions to the forum: https://forum.riot-os.org/t/moving-from-community-processes-to-governance-md/4433/2

[miri64]

Rebased and squashed to resolve merge conflicts.

[miri64]

Another rebase due to the fix in #21090.

[kfessel]

other .md files (eg.CoC, CONTRIBUTING.md) seem to have some line length limit applied (maybe 100 with url exception)

But you are probably just saving this for the squash