Skip to content

Commit bf96c73

Browse files
Brend-SmitsBrend-Smits
committed
docs: add governance model and update maintainers guide
1 parent efbaa6f commit bf96c73

File tree

2 files changed

+91
-9
lines changed

2 files changed

+91
-9
lines changed

‎GOVERNANCE.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Governance Model
2+
3+
This document describes the governance model for the **terraform-aws-github-runner** project. It defines how decisions are made, how contributors can grow their involvement, and what is expected of maintainers.
4+
5+
## Communication
6+
7+
### Public Discussion
8+
9+
The primary place for community discussion is **GitHub** — issues and pull requests are the preferred venue for bug reports, feature proposals, and design conversations. This keeps decisions transparent and discoverable.
10+
11+
For more informal discussion, questions, and real-time conversation, we also have a [Discord](https://discord.gg/bxgXW8jJGh) server. All contributors and users are welcome to join.
12+
13+
### Maintainer Discussion
14+
15+
Maintainers have a private channel on Discord to discuss sensitive topics, such as security issues, onboarding new maintainers, and matters that are not yet ready for public discussion. Decisions reached in the private channel are communicated back to the community once they are ready.
16+
17+
## Roles
18+
19+
### Contributor
20+
21+
Anyone who opens an issue, submits a pull request, or participates in discussion is a contributor. No special access is required.
22+
23+
### Collaborator
24+
25+
Contributors who have shown sustained interest in the project may be invited as **collaborators** on the GitHub repository. Collaborators can be assigned to issues and pull requests and are expected to participate actively in reviews and discussions. This role is a stepping stone toward becoming a maintainer.
26+
27+
If you are interested in becoming a collaborator or maintainer, you can express this by opening a pull request to add yourself to [MAINTAINERS.md](MAINTAINERS.md).
28+
29+
### Maintainer
30+
31+
Collaborators who have demonstrated trustworthiness, good judgement, and a thorough understanding of the project may be promoted to **maintainer**. Maintainers can approve and merge pull requests and have commit access to the repository.
32+
33+
The current maintainers are listed in [MAINTAINERS.md](MAINTAINERS.md).
34+
35+
#### Becoming a Maintainer
36+
37+
The path to maintainership is:
38+
39+
1. Contribute code, documentation, or reviews over a sustained period.
40+
2. Be invited as a collaborator by an existing maintainer.
41+
3. Continue demonstrating good judgement and reliability.
42+
4. Be proposed and agreed upon by the existing maintainers (via the private Discord channel).
43+
5. Be added to [MAINTAINERS.md](MAINTAINERS.md) and granted merge permissions.
44+
45+
There is no fixed timeline; promotion is based on demonstrated trust and engagement.
46+
47+
#### Stepping Down or Being Removed
48+
49+
Maintainers who are no longer able to actively contribute are encouraged to step down. They can do so at any time by opening a pull request to remove themselves from [MAINTAINERS.md](MAINTAINERS.md) or by notifying another maintainer directly.
50+
51+
If the maintainers collectively notice a prolonged absence or lack of engagement from a maintainer, they may reach out to check in. If no response is received or the maintainer confirms they are no longer able to contribute, they may be removed from [MAINTAINERS.md](MAINTAINERS.md) by a pull request approved by the remaining maintainers. This is not a punitive measure — it is done to keep the list accurate and the project healthy.
52+
53+
## Decision Making
54+
55+
Most changes are discussed openly via GitHub issues and pull requests, with consensus reached through review comments. For larger design decisions, the Discord community is the primary forum.
56+
57+
Maintainers make final decisions on pull request merges. Where there is disagreement among maintainers, the discussion moves to the Discord channel to reach a resolution.
58+
59+
### Pull Request Approval Policy
60+
61+
- A pull request can be merged once it has received **at least one maintainer approval**, provided no other maintainer has explicitly requested changes.
62+
- To avoid the equivalent of checking your own homework, **maintainers from the same company must not be the sole approver of each other's pull requests**. At least one approval from a maintainer at a different organisation is required before such a PR can be merged.
63+
64+
## Testing Requirements
65+
66+
At this time, maintainers are expected to have access to their own AWS account for manual and exploratory testing of pull requests. We recognise this is a barrier and are actively exploring options for a sponsored or shared AWS environment to make contributions and automated testing more accessible. If you are aware of or able to provide such sponsorship, please reach out via Discord or open an issue.
67+
68+
## Changes to This Document
69+
70+
Changes to this governance model should be proposed via a pull request and require approval from at least two maintainers.

‎MAINTAINERS.md‎

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,27 @@
11
# Maintainers guide
22

3-
Roles and responsibilities of the maintainers of the project.
3+
Roles and responsibilities of the maintainers of the project. For the full governance model — including how decisions are made, how roles are assigned, and how maintainers can step down or be removed — see [GOVERNANCE.md](GOVERNANCE.md).
4+
5+
## Collaborators
6+
7+
Collaborators are contributors who have shown sustained interest in the project and have been invited to take a more active role. See [GOVERNANCE.md](GOVERNANCE.md) for details on the path from contributor to collaborator to maintainer.
8+
9+
If you are interested in becoming a collaborator or maintainer, open a pull request to add yourself to this file. The existing maintainers will use that PR as a place for a joint discussion on whether the timing is right.
10+
11+
| Name | GitHub Handle | Affiliation |
12+
| ---- | ------------- | ----------- |
13+
| - | - | - |
414

515
## Maintainers
616

7-
| Name | GitHub | Affiliation |
8-
| ----------------- | ------------------- | ---------------- |
9-
| Niek Palm | [@npalm] | Philips |
10-
| Koen de Laat | [@koendelaat] | Philips |
11-
| Guilherme Caulada | [@guicaulada] | Grafana Labs |
12-
| Ederson Brilhante | [@edersonbrilhante] | Cisco |
13-
| Brend Smits | [@Brend-Smits] | Philips |
14-
| Stuart Pearson | [@stuartp44] | Philips |
17+
| Name | GitHub Handle | Affiliation |
18+
| ----------------- | ------------------- | ------------ |
19+
| Niek Palm | [@npalm] | Philips |
20+
| Koen de Laat | [@koendelaat] | Philips |
21+
| Guilherme Caulada | [@guicaulada] | Grafana Labs |
22+
| Ederson Brilhante | [@edersonbrilhante] | Cisco |
23+
| Brend Smits | [@Brend-Smits] | Philips |
24+
| Stuart Pearson | [@stuartp44] | Philips |
1525

1626
## Responsibilities
1727

@@ -21,6 +31,8 @@ Maintainers are responsible to review and merge pull requests. Currently we have
2131

2232
#### Guidelines
2333

34+
- A pull request can be merged once it has **at least one maintainer approval**, provided no other maintainer has explicitly requested changes.
35+
- **Maintainers from the same company must not be the sole approver of each other's pull requests.** At least one approval from a maintainer at a different organisation is required before such a PR can be merged.
2436
- Check if changes are implemented for both modules (root and multi-runner)
2537
- Check backwards compatibility, we strive to keep the module compatible with previous versions
2638
- Check complexity of the changes, if the changes are too complex. Think about how does impact the PR on the long term maintaining the module.

0 commit comments

Comments
 (0)