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

4f6d46d README.md: Add a link to GOVERNANCE.md

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

Artifacts

• Documentation preview

[mguetschow]

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

[miri64]

Quoting from #21067 (comment) as this is somewhat lost in truncation.

also, this is a bit unclear. How do we know that "all bug-fixing point releases are out"? Just before starting a new (soft/hard) feature freeze for the next release ?

I think that is something we need to decide on. Because I don't know an answer to your questions.

[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.

[jkarinkl]

How is decided what 'failure to fulfill their Maintainer responsibilities' or 'for other reasons' is and thus when someone should be removed as maintainer?

Answering this question (and adding something in this text) is relevant if this is a point where a healthy working process can get stuck (e.g., not getting to an agreement whether a maintainer should be removed or not, resulting in nothing happening and more of these situations can occur in the future).

If this is not expected to become an issue, no additions to this text are needed. (referencing to my general 'describe the process steps when it prevents big problems, otherwise a general description is ok').

[miri64]

I don't expect this to become an issue. But maybe others do?

[jkarinkl]

It is not directly clear to me what is meant here with stakeholders. I saw the earlier discussion on it, and therefore understand the choosing of this word. This may not be clear to someone fresh reading the text.

Maybe there can be added a word overview to the document, explaining what is meant with 'stakeholders' in this document? Something showing that within the RIOT community there are many people who are part of an organization/institute and work from that institute on RIOT, but we also have individuals not belonging to an organization and want to address them all alike.

[miri64]

Something like 30a2f85?

[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.