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
Post New Year summary: https://forum.riot-os.org/t/moving-from-community-processes-to-governance-md/4433/9

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

acb81c8 README.md: Add a link to GOVERNANCE.md

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

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.

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

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.

[MrKevinWeiss]

ping @mguetschow have your comments been addressed. If everyone agrees I would like to get this in before the hard freeze.

[MrKevinWeiss]

So from what I have seen, there is nothing too controversial. It is mostly putting words to how we currently operate. I am fine getting this in but probably we should get another ACK from someone more opinionated.

[maribu]

+1 for merge now. As always, we can refine later.

[mguetschow]

Just another two small typos, apart from that I'm fine with the content. Thanks for all your comments and especially your work on this @miri64!

[chrysn]

There are aspects I think we could do better (more openness on weeklies and s/VMA/VGA/), but this PR's point is not about changing procedure and more about documenting it, and this seems to be reasonably accurate where I know how it works and it matters.

[OlegHahm]

I share the feeling of the previous reviewers. Good enough for now and quite accurate documentation of the status quo. Thanks a bunch for great effort, @miri64!

[miri64]

Thanks for your reviews!

[miri64]

Addressed #21067 (review) as a last step, you can confirm that this does not change the text with

git diff --word-diff  388955a  acb81c8

diff --git a/GOVERNANCE.md b/GOVERNANCE.md
index 7e0bbae35b..94e5860b7b 100644
--- a/GOVERNANCE.md
+++ b/GOVERNANCE.md
@@ -1,6 +1,7 @@
# Governance of the RIOT Community

The RIOT community is dedicated to creating a free and open source operating system for the
constrained Internet of Things [[RFC7228], [draft-ietf-iotops-7228bis]] based on open standards.
This document explains the governance of the project.

<!-- TOC start -->
@@ -26,32 +27,36 @@ This document explains the governance of the project.

The RIOT community embraces the following values:

* **Openness:** Communication and decision-making happens in the open and is discoverable for future
  reference. As much as possible, all discussions and work events eventually take place in public
  forums and open repositories. Ideas might be shared and brainstormed in confidence among
  contributors at first but there should always be a point when this process becomes open to the
  community at large.

* **Fairness:** All stakeholders have the opportunity to provide feedback and submit contributions,
  which will be considered on their merits.

* **Community over Product or Company:** Sustaining and growing our community takes priority over
  shipping code or sponsors' organizational goals. Each contributor participates in the project as
  an individual.

* **Inclusivity:** We innovate through different perspectives and skill sets, which can only be
  accomplished in a welcoming and respectful environment.

* **Participation:** Responsibilities within the project are earned through participation, and
  contributors can grow into more responsible positions.


## Community Processes
The community around RIOT gathers many IoT developers and users from around the world, from the
industry, from academia, and hobbyists. The RIOT community is open to everyone. Our channels to
communicate can be found in our [contributing guidelines]. The community self-organizes using the
roles described below.


## Roles
### Contributors
Contributors are people who contribute their work to RIOT. This includes,

- of course, code contributions, but also
- writing documentation,
@@ -61,92 +66,111 @@ This includes,
- participation in technical as well as non-technical discussions, or
- organizational considerations.

Code contributions are very welcome. In order to streamline and harmonize code quality, contributors
must follow the [contributing guidelines].

Contributors may be associated with organizations—by employment or otherwise—who have a vested
interest in RIOT or may be individuals who have their own personal stakes in RIOT. We call these
organizations and individuals “stakeholders” throughout this document to summarize them.

### Maintainers

Among contributors, some have maintainer status, which consists in rights (write access to the [RIOT
GitHub repository](https://github.com/RIOT-OS/RIOT/)) and duties. The current maintainers can be
found in the [maintainers list].

Maintainers are people who care about RIOT and want to help it grow and improve. A maintainer is not
just someone who can make changes, but someone who has demonstrated their ability to collaborate and
organize with the team, get the most knowledgeable people to review code or documentation,
contribute high-quality code or documentation, as well as follow through to fix issues (in code,
tests, or tests). More on maintaining RIOT can be found in the [maintaining guidelines].

We are constantly looking for more maintainers. So if you are up for that, please start (or
continue) contributing code and reviews!

To contact maintainers, the best is to interact over actual RIOT code on
[GitHub](https://github.com/RIOT-OS/RIOT/pulls).

#### Becoming a Maintainer

Maintainers can propose to give maintainer status to contributors that have been noticed as
particularly active in some domain of RIOT. Of course, contributors can also step forward themselves
and declare their interest to become a maintainer. In this case, maintainers should then propose
them as well, if their activities can be confirmed. The decision to grant this status is then taken
via consensus among the maintainers. If there is consensus on granting the status to a particular
contributor, a maintainer will personally contact this contributor with the proposal, which the
contributor can then accept (or turn down).

At the discretion of the proposing maintainer (typically 1 or 2 weeks after the proposal), a new
maintainer who is selected will be

- invited to the [maintainers GitHub team] by one of the admins of the RIOT project, which grants
  them the necessary GitHub rights,
- invited to the maintainer forum group by the forum moderators, which will give them access to the
  (private) maintainer part of the forum, and
- invited to the RIOT-maintainer chat room by one of the moderators of that room, for more informal
  exchanges between maintainers.

#### Removing a Maintainer

Maintainers may resign at any time if they feel that they will not be able to continue fulfilling
their project duties.

Maintainers may also be removed after being inactive, upon failure to fulfill their Maintainer
responsibilities or because of violating the Code of Conduct. This also includes actively,
persistently, and intentionally trying to harm or successfully harming the code base of RIOT.
Especially, but not limited to, endangering the security or safety of RIOT. Inactivity is defined as
a period of very low or no activity in the project. A yearly maintainer ping, an e-mail sent to
inactive maintainers, determines if the maintainer is still willing to fulfill their project duties.
During this process, the list of maintainers is reviewed. On failure to reply to the maintainer ping
within the specified amount of time (usually a month), the maintainer will be removed.

### Release Managers

Release managers make sure the quarterly release comes out in time. They are one or more maintainers
which were appointed for a specific release by the Virtual Maintainer Assembly (VMA). Their duties
include setting the dates for feature freeze for the release, enforcing the feature freeze,
coordinating the (mostly automated) tests of a release, writing the release notes and creating the
tags defining the release and its release candidates. The full set of tasks can be found in the
document [Managing a Release]. Their duties end after the release they managed is out and all
bug-fixing point releases to their release are finished.

### Admins

GitHub admins are a special subgroup among RIOT maintainers. They are marked as such in the
[maintainers list]. They have more access rights to the RIOT repositories, such as granting access
to a repository, adding new members to a team, or enabling protection for Git branches. Release
managers might need to contact GitHub admins to configure the branch protection rules for the
release branch. Beyond those technical duties and access rights, they do not have any special rights
among maintainers. They are picked by the maintainers, usually based on seniority. The maintainers
try to take care to spread the admin responsibility over several project stakeholders within the
maintainer body. This is to aspire some checks and balances between stakeholders as well as
introduce redundancies in case a stakeholder is not able to work on RIOT anymore.

There are also admins on the other RIOT discussion platforms. Beyond technical administrative duties
they do not have any special rights. These admins usually are appointed or self-appointed on merit,
i.e., whoever sets up the platform usually is (one of) its admin(s).

### GitHub Owners
Github owners are a special subgroup among RIOT GitHub admins. They are marked as such in the
[maintainers list]. Beyond this special status and the usual GitHub admin rules and duties they do
not have any special rights among maintainers.

### Moderators

Moderators are responsible to enforce the values of the RIOT community within its discussion
platforms. Each platform usually has its own set of moderators, a list of which can be found there.
The forum moderators, e.g., can be found [here](https://forum.riot-os.org/g/moderators) (link
requires you to be logged into the forum). The tools at the disposal of the moderator are also very
platform-dependent but in general, they try to resolve conflicts that may arise between
contributors, unless a [Code of Conduct] violation takes place. Moderators are people that the
community put their trust upon. As such, they are granted this status via consensus from the
community. Typically, other moderators may propose new moderators.

## Decision Making
Decisions within the RIOT community are made on the principles of “rough consensus and running code”
as [coined by the IETF](https://datatracker.ietf.org/doc/html/rfc7282). To directly quote RFC 7282
which defines the IETF governance:

>   […] our credo is that we don't let a single individual dictate
>   decisions (a king or president), nor should decisions be made by a
@@ -167,9 +191,9 @@ Decisions within the RIOT community are made on the principles of “rough conse
>   chair can declare that there is rough consensus to go forward, the
>   objection notwithstanding.

Within the RIOT community, the duties of an IETF working group chair fall to maintainers
knowledgeable in the area of expertise. This knowledgability is determined by their own
contributions. On decisions regarding a release, the release manager(s) take this position.

## Meetings

@@ -180,45 +204,53 @@ There are three types of regular meetings within the RIOT community:
- The Weekly Coordinational Meeting.

The GA is public and anyone who sees themselves as a member of the RIOT community can participate.
Larger community steering decisions for the community are made during the GA, e.g., electing contact
people for the Code of Conduct. The GA usually takes place during the [RIOT
Summit](https://summit.riot-os.org/), the annual get-together of the RIOT community. The GA
moderator usually is appointed by the organizers of the RIOT Summit. It is usually recorded and its
notes will be published publicly in the RIOT forum. The agenda for the GA is collected before the
assembly but may be bashed at the start of the meeting.

The Virtual Maintainer Assembly (VMA) is a closed meeting among maintainers. The VMA appoints the
release manager for upcoming releases and the moderator for the next VMA. Other maintenance
decisions such as the fate of larger sections of code are discussed after these administrative tasks
are done. The VMA usually takes place about a month after the latest release, usually in a virtual
space, such as a video conference. The VMA moderator polls the maintainers for a sufficient date
around the date of the upcoming release. Every forth VMA may or may not co-incide with the GA.
However, the VMA moderator usually decides to merge these two meetings. In this case, VMA moderator
and RIOT Summit organizers decide together on who is moderating the joint event (it may be the VMA
moderator, it may be someone else). The agenda for the VMA is collected before the assembly but may
be bashed at the start of the meeting. The notes of the VMA will be published publicly in the RIOT
forum.

The Weekly Coordinational Meeting is a closed meeting among maintainers. It usually serves as a
small communal get-together of maintainers on a regular basis. Smaller maintenance decisions are
made during these meetings, but also short term admistrative tasks are discussed. The Weekly
Coordinational Meeting usually takes place every Friday at 10:00 in a virtual space, such as a video
conference. A maintainer that feels responsible for it shares the link to the meeting as well as a
proposed agenda, which may be amended by other maintainers, usually a day in advance.

## Code of Conduct

[Code of Conduct] violations by community members will be discussed and resolved on the
[email protected] list. If one of the appointees to that list (see the [Code of Conduct reporting
guidance] for the members on that list) is involved in a Code of Conduct violation, two forum
moderators from other stakeholders than the appointee take their place in the discussions.

## Security Response Team

The maintainers will appoint a Security Response Team to handle security reports. This committee may
simply consist of the maintainers themselves. The Security Response Team is responsible for handling
all reports of security holes and breaches according to the [security policy].

## Modifying this Charter

Changes to this Governance and its supporting documents require the approval of at least four
maintainers who all must be employed by or associated with different stakeholders.

## Attribution
This document was originally based on the [GOVERNANCE-maintainer.md template] by the Cloud Native
Computing Foundation (CNCF).

[RFC7228]: https://datatracker.ietf.org/doc/html/rfc7228
[draft-ietf-iotops-7228bis]: https://datatracker.ietf.org/doc/draft-ietf-iotops-7228bis/