You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document describes how the Mellea project is governed: the roles people hold, how decisions are made, and how code gets reviewed and merged.
3
+
This document describes how the Mellea project is governed: the roles people hold, how decisions are made, and how code gets reviewed and merged. This governance applies across the Mellea ecosystem, including the [mellea](https://github.com/generative-computing/mellea) and [mellea-contribs](https://github.com/generative-computing/mellea-contribs) repositories. Repo-specific policies are noted where they apply.
4
4
5
5
For related topics, see:
6
6
@@ -13,23 +13,26 @@ For related topics, see:
13
13
| Role | Description | Examples |
14
14
|------|-------------|----------|
15
15
|**Contributor**| Anyone who opens issues, submits pull requests, or participates in discussions. No special access required. | External collaborators, first-time contributors |
16
-
|**Maintainer**| Has merge/write access to the repository and responsible for code review. Member of [`@generative-computing/mellea-maintainers`](https://github.com/orgs/generative-computing/teams/mellea-maintainers). | Team members with maintainer rights |
17
-
|**Code Owner**| Domain expert listed in [`.github/CODEOWNERS`](.github/CODEOWNERS). Automatically requested as a reviewer for PRs touching their area. | Core library owners, intrinsics team |
16
+
|**Member**| An established contributor who has demonstrated sustained interest through multiple contributions. Members are added to the GitHub organization and gain the ability to be assigned to issues and PRs, automatic CI runs on their PRs, and eligibility to review PRs. | Organization members |
17
+
|**Module Maintainer**| Responsible for the health and direction of a specific area of the codebase or a specific package. Has authority to approve and merge PRs within their area. | Core library maintainers, intrinsics team, contribs package maintainers |
18
+
|**Maintainer**| Has project-wide merge/write access and responsible for code review across the repository. Member of [`@generative-computing/mellea-maintainers`](https://github.com/orgs/generative-computing/teams/mellea-maintainers). Maintainers hold release authority and the ability to grant access to new members and module maintainers. | Team members with maintainer rights |
18
19
19
-
New maintainers are added by invitation from existing maintainers, based on sustained, high-quality contributions. Release authority and the ability to grant maintainer access are held by a subset of maintainers with admin privileges.
20
+
Current module ownership in mellea:
20
21
21
-
## Code Ownership
22
-
23
-
[`.github/CODEOWNERS`](.github/CODEOWNERS) defines required reviewers per area of the codebase. GitHub automatically requests reviews from the appropriate owners when a PR touches their files.
In the mellea repository, module maintainers are listed in [`.github/CODEOWNERS`](.github/CODEOWNERS) and automatically requested as reviewers for PRs touching their area.
2.**Become a member** — After multiple meaningful contributions, request membership (or be nominated). Requires sponsorship by at least one existing member or maintainer.
33
+
3.**Become a module maintainer** — After demonstrating familiarity with an area through contributions and reviews, you may be nominated by an existing maintainer. Nomination is accepted if there are no objections from other maintainers of that area within one week.
34
+
4.**Become a maintainer** — After demonstrating sustained, high-quality contributions across the project, you may be invited by existing maintainers.
35
+
33
36
## PR Review & Merge Policy
34
37
35
38
### What approval means
@@ -38,7 +41,7 @@ A GitHub approval is equivalent to an Apache-style **LGTM** and **implies owners
38
41
39
42
### Requesting reviews
40
43
41
-
If you explicitly tag someone as a reviewer, you are asking for their review specifically. All explicitly requested reviewers should approve before the PR is merged. CODEOWNERS also enforces required reviewers automatically — PRs cannot be merged until all required code-owner reviews are satisfied.
44
+
If you explicitly tag someone as a reviewer, you are asking for their review specifically. All explicitly requested reviewers should approve before the PR is merged. In mellea, CODEOWNERS also enforces required reviewers automatically — PRs cannot be merged until all required code-owner reviews are satisfied.
42
45
43
46
### Reviewing
44
47
@@ -53,27 +56,184 @@ Once a PR has approvals from all requested and required reviewers:
53
56
-**Author has commit rights** — the author may merge or enable auto-merge.
54
57
-**Author is an external contributor** — the approver is responsible for merging.
55
58
59
+
Pull requests require the following before merging:
60
+
61
+
1.**At least one review** from a member, module maintainer, or maintainer
62
+
2.**Approval from a module maintainer** (or maintainer) for the affected area or package
63
+
3.**All CI checks pass**
64
+
4.**No unresolved "request changes" reviews**
65
+
66
+
In mellea-contribs, pull requests that span multiple packages require approval from a module maintainer of each affected package (or a maintainer).
67
+
56
68
### PR scope
57
69
58
70
Keep PRs focused on one logical change. Smaller, well-scoped PRs are easier to review, faster to merge, and safer to revert if needed.
59
71
72
+
### Contributor responsibility
73
+
74
+
When a PR is accepted, the maintainers inherit both an asset and a liability: the new functionality is (hopefully) an asset, but the code and documentation required to support it are ongoing liabilities. Reviewers invest real time reading and understanding every PR.
75
+
76
+
Contributors are responsible for every line they submit. Do not ask others to read and maintain code or documentation that you have not taken the time to read, understand, and refine yourself. This applies regardless of how the code was produced — whether written by hand or generated with AI tools.
77
+
78
+
**Use of AI tools:** We neither prohibit nor discourage the use of AI coding assistants. However, AI-generated code is not exempt from this standard. If you use AI tools to produce code or documentation, you are expected to review, understand, and take full ownership of the output before submitting it for review. The reviewer's time is not the place to discover what the AI wrote on your behalf.
79
+
60
80
### Merge queue
61
81
62
82
All PRs merge through GitHub's [merge queue](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue). After approval, PRs enter the queue, which runs CI against the latest `main` before landing. This ensures that every commit on `main` has passed the full test suite.
63
83
64
84
## Decision-Making
65
85
66
86
-**Day-to-day changes** (bug fixes, small features): lazy consensus via PR review. If a PR is approved and CI passes, it can be merged.
67
-
-**Significant changes** (new core abstractions, new backends, breaking API changes): open a GitHub issue for discussion before submitting a PR. These changes should receive broader review from maintainers and relevant code owners.
68
-
-**Disputes**: escalate to maintainers. If consensus cannot be reached, the project lead makes the final call.
87
+
-**Significant changes** (new core abstractions, new backends, breaking API changes): open a GitHub issue for discussion before submitting a PR. These changes should receive broader review from maintainers and relevant module maintainers.
88
+
-**Disputes**: escalate to maintainers. If consensus cannot be reached, decisions are made by majority vote of the maintainers.
89
+
90
+
In mellea-contribs, module maintainers use lazy consensus within their package — a proposal is considered accepted if no module maintainer objects within a reasonable timeframe.
69
91
70
92
## Releases
71
93
72
-
Maintainers hold release authority. The full release process — including cadence, versioning, and automation — is documented in [RELEASE.md](RELEASE.md).
94
+
In mellea, maintainers hold release authority. The full release process — including cadence, versioning, and automation — is documented in [RELEASE.md](RELEASE.md).
95
+
96
+
In mellea-contribs, each package has its own release cadence, managed by its module maintainer(s). There is no project-wide release schedule — packages are released independently as their module maintainers see fit. The maintainers may coordinate releases when cross-package changes require it.
73
97
74
98
## Communication
75
99
76
100
-**GitHub Issues and Pull Requests** — code-related decisions and technical discussion
77
101
-**GitHub Discussions** — broader topics, questions, and ideas
78
102
79
103
All community interactions are subject to the [Code of Conduct](CODE_OF_CONDUCT.md).
104
+
105
+
## mellea-contribs
106
+
107
+
The [`mellea-contribs`](https://github.com/generative-computing/mellea-contribs) repository is an incubation point for contributions to the Mellea ecosystem. It contains multiple packages — framework integrations, tools, and libraries — each of which may be maintained by different individuals or teams.
108
+
109
+
### Package Requirements
110
+
111
+
Every package in the repository must meet the following standards:
112
+
113
+
-**`pyproject.toml`** — Each package is a self-contained Python project with its own `pyproject.toml` defining dependencies, metadata, and tool configuration.
114
+
-**Tests** — Each package must include a `tests/` (or `test/`) directory with at least one test module. All tests must be runnable via `pytest`. See [Testing](#testing) for details.
115
+
-**CI** — Packages do not need their own CI workflow files. The repository-level CI workflows automatically discover updated packages and run quality checks (linting, type checking, tests) against them.
116
+
-**Documentation** — Each package must include a README with usage documentation. Packages may also include a CONTRIBUTING.md if their contribution workflow has package-specific requirements.
117
+
-**License** — Each package must use a license compatible with the project (Apache 2.0 preferred).
118
+
119
+
### Package Structure
120
+
121
+
Packages live under `mellea_contribs/` and follow this general layout:
122
+
123
+
```
124
+
mellea_contribs/<package_name>/
125
+
├── pyproject.toml
126
+
├── README.md
127
+
├── src/
128
+
│ └── <import_name>/
129
+
│ └── ...
130
+
└── tests/
131
+
├── test_*.py
132
+
└── external/ # optional
133
+
└── test_*.py
134
+
```
135
+
136
+
### Package Ownership
137
+
138
+
Each package has one or more designated module maintainers who are responsible for its health and direction. Module maintainers have autonomy over technical decisions within their package, including:
- Internal test organization and contribution guidelines
144
+
145
+
The maintainers retain override authority on any decision and may intervene when:
146
+
147
+
- A package decision affects other packages or the project as a whole
148
+
- Project-wide standards or policies are not being met
149
+
- A package becomes unmaintained
150
+
151
+
### Package Maintenance
152
+
153
+
Module maintainers are expected to keep their packages in good working order. This means:
154
+
155
+
-**CI stays green** — Tests should be passing on the main branch. Flaky or broken tests should be addressed promptly, not left failing.
156
+
-**Dependencies stay current** — Packages must specify minimum and maximum compatible versions of Mellea core in their `pyproject.toml` (e.g., `mellea>=0.5.0,<0.7.0`). When Mellea core releases a new version, module maintainers should verify compatibility and update these bounds as needed. Packages that fall too far behind supported Mellea versions may be candidates for deprecation or removal.
157
+
-**Python version support** — Packages should support the Python versions tested in CI (currently 3.11, 3.12, and 3.13). When the project adds or drops Python versions, module maintainers should update accordingly.
158
+
-**Documentation stays accurate** — READMEs and usage docs should reflect the current state of the package. Outdated documentation is a maintenance issue.
159
+
-**Security issues are addressed** — Dependabot alerts, reported vulnerabilities, and security-related issues should be treated as high priority.
160
+
161
+
#### When a Package Falls Behind
162
+
163
+
If a package is not meeting the standards above, the following escalation path applies:
164
+
165
+
1.**The maintainers flag the issue** — by opening an issue on the package describing what needs attention.
166
+
2.**The module maintainer has a reasonable window to respond** — either by fixing the issue, providing a timeline, or explaining why the current state is acceptable.
167
+
3.**If there is no response**, the maintainers may seek a new module maintainer by posting a call for volunteers.
168
+
4.**If no new module maintainer steps up**, the maintainers may retire the package (see [Retiring Packages](#retiring-packages)).
169
+
170
+
The goal is not to be punitive — module maintainers are volunteers and life happens. The escalation path exists to ensure that packages in the repository remain usable and trustworthy for the broader community.
171
+
172
+
### Accepting New Packages
173
+
174
+
To propose a new package, open an issue describing:
175
+
176
+
1. The package's purpose and scope
177
+
2. How it fits within the Mellea ecosystem (i.e., what need it addresses that is not already covered)
178
+
3. Who will maintain it
179
+
180
+
The maintainers will review and decide on acceptance. Accepted packages must meet all the [Package Requirements](#package-requirements) before merging.
181
+
182
+
### Retiring Packages
183
+
184
+
A package may be retired by the maintainers if:
185
+
186
+
- It has no active module maintainer and no one volunteers to take over
187
+
- It is superseded by functionality in another package or in Mellea core
188
+
- It no longer meets project-wide standards and the module maintainer is unresponsive
189
+
190
+
Retired packages will be removed from the repository. The maintainers will make reasonable efforts to notify users and provide a migration path before removal.
191
+
192
+
### Promotion to Mellea Core
193
+
194
+
Packages that prove their value in `mellea-contribs` may be promoted directly into Mellea core. Promotion is not automatic — it is a recognition that a package has become essential to the ecosystem.
195
+
196
+
#### Criteria
197
+
198
+
The maintainers will consider factors such as:
199
+
200
+
-**Stability** — How long the package has been in the repository and its track record of passing CI.
201
+
-**Community adoption** — Evidence of real-world usage, such as downloads, issues filed by users, or adoption by other packages.
202
+
-**Active maintenance** — Whether the module maintainer is responsive and keeps the package up to date.
203
+
-**Test coverage and documentation** — The overall quality and completeness of the package's test suite and docs.
204
+
205
+
#### Process
206
+
207
+
1.**Open a GitHub Discussion** — Anyone (maintainer, user, or module maintainer) can propose a package for promotion by opening a discussion in the repository.
208
+
2.**Community input** — The discussion should remain open for a reasonable period to gather feedback from maintainers, users, and module maintainers.
209
+
3.**Maintainer decision** — The maintainers review the proposal against the criteria above and make a final decision.
210
+
4.**Migration** — If approved, the maintainers coordinate with the module maintainer to migrate the package into Mellea core.
211
+
212
+
### Testing
213
+
214
+
Every package is required to have its own test suite. This section describes project-wide testing conventions; individual packages may layer on additional requirements.
215
+
216
+
#### Requirements
217
+
218
+
1.**Test directory** — Every package must contain a `tests/` (or `test/`) directory with at least one test module.
219
+
2.**Test runner** — All tests must be runnable via `pytest`.
220
+
3.**CI workflow** — Every package must have a CI workflow file that calls the shared `quality-generic.yml` workflow.
221
+
4.**Tests must pass** — A package's CI checks must pass for any PR that touches that package. Failures in one package do not block PRs to other packages.
222
+
223
+
#### Conventions
224
+
225
+
-**External tests** — Tests that require external services (LLM providers, Ollama, APIs) should be placed in a `tests/external/` subdirectory or marked with `@pytest.mark.external`. External tests are excluded from CI by default (`--ignore=tests/external`).
226
+
-**Async support** — Use `asyncio_mode = "auto"` in `pyproject.toml` so async tests do not need explicit `@pytest.mark.asyncio` decorators.
227
+
-**Custom markers** — Packages that define custom pytest markers (e.g., `qualitative`, `slow`, `requires_api_key`) should document them in their `pyproject.toml` under `[tool.pytest.ini_options]`.
228
+
229
+
## Evolution of This Document
230
+
231
+
This governance model is intentionally lightweight. As the contributor community grows, we expect to add:
232
+
233
+
- Formal inactivity and emeritus policies
234
+
- A CODEOWNERS file mapping mellea-contribs packages to module maintainers
235
+
- Company diversity guidelines for module maintainer nominations
236
+
- A structured proposal process for significant cross-package changes
237
+
- Detailed voting and escalation procedures
238
+
239
+
Changes to this document require approval from the maintainers.
0 commit comments