Skip to content

Commit f2736e6

Browse files
dmealingdmealing
authored
docs: add GOVERNANCE.md and MAINTAINERS.md, link them from README and CONTRIBUTING (#495)
* docs: add GOVERNANCE.md and MAINTAINERS.md, link them from README and CONTRIBUTING GOVERNANCE.md sets out the three roles (contributor, port maintainer, core maintainer), how merge and publish rights are earned, lazy consensus with core-maintainer approval for the model format, ADRs and releases, the creator's scoped tie-break and veto, ownership of the org, namespaces and trademark, succession, and stepping down. MAINTAINERS.md lists the creator as the sole maintainer, every port and area as maintainer wanted, and today's registry owners. * no-mistakes(review): Scope creator tie-break; fix succession even-split rule
1 parent d54c9fd commit f2736e6

4 files changed

Lines changed: 255 additions & 1 deletion

File tree

‎CONTRIBUTING.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@ conformance corpora. This guide covers how to propose changes.
1111
label for low-barrier, well-scoped starting points.
1212
- This is a primarily one-person, part-time project — issues and PRs are welcome, but
1313
expect reviews on the order of days, not hours.
14+
- Want to maintain a port or an area? [GOVERNANCE.md](GOVERNANCE.md) sets out the roles,
15+
how merge and publish rights are earned, and how decisions are made.
16+
[MAINTAINERS.md](MAINTAINERS.md) lists who maintains what today; every port is open.
1417
- For anything non-trivial (new metamodel behavior, a new generator, a cross-language
1518
change), **open an issue first** to discuss the approach. Small, obvious fixes can go
1619
straight to a PR.
@@ -30,7 +33,9 @@ conformance corpora. This guide covers how to propose changes.
3033
release tags, so your local run is the only check of the rest before merge — see the
3134
*Local CI* section below.
3235
4. Open a **pull request** against `main` and fill out the PR template.
33-
5. A maintainer reviews the change and the checks on the pull request before merge.
36+
5. A maintainer reviews the change and the checks on the pull request before merge. Who can
37+
approve what, and which changes need a core maintainer, is in
38+
[GOVERNANCE.md](GOVERNANCE.md#how-decisions-are-made).
3439

3540
## The cardinal rule: the metamodel is the spine
3641

‎GOVERNANCE.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Governance
2+
3+
This file says who can do what in the MetaObjects project, how someone earns more rights, and
4+
how decisions are made. [MAINTAINERS.md](MAINTAINERS.md) lists who holds each role today.
5+
6+
MetaObjects is primarily a one-person, part-time project. Today the creator, Doug Mealing, is the
7+
only maintainer. These rules are written down now so that a second maintainer knows the terms
8+
before putting in time.
9+
10+
## Roles
11+
12+
There are three roles.
13+
14+
| Role | Who | What they can do |
15+
|---|---|---|
16+
| Contributor | Anyone who opens an issue, a pull request, a review or a discussion | Propose changes. Review any pull request. Their reviews count toward earning a maintainer role |
17+
| Port maintainer | Someone who owns one area: a language port, the web client, the docs, a generator family or a library (the areas are listed in [MAINTAINERS.md](MAINTAINERS.md)) | Review and merge pull requests that stay inside their area. Triage and label its issues. Publish that area's registry packages once publish rights are granted (see below) |
18+
| Core maintainer | Someone responsible for the project as a whole | Everything a port maintainer can do, in every area. Approve changes to the model format, ADRs and releases. Grant and remove roles |
19+
20+
A person can maintain more than one area. Core maintainers can merge in any area, but should
21+
leave a pull request to the area's port maintainer when there is one.
22+
23+
## How rights are earned
24+
25+
### Becoming a port maintainer
26+
27+
The usual bar is:
28+
29+
- at least 5 merged pull requests in the area, and
30+
- about 2 months of reviewing other people's pull requests in that area.
31+
32+
Anyone can propose a person, including themselves, by opening an issue that links the merged
33+
pull requests and reviews. A core maintainer then decides, using the decision process below.
34+
The bar is a guide. A core maintainer can accept someone earlier when their work makes the case,
35+
and should say why on the issue.
36+
37+
When the role is granted, the person is added to [MAINTAINERS.md](MAINTAINERS.md) and given write
38+
access to the repository. Branch protection still applies to them like everyone else.
39+
40+
### Publish rights
41+
42+
Each port publishes to its own registry: npm for TypeScript and the web client, Maven Central
43+
for Java and Kotlin, NuGet for C#, PyPI for Python. Publish rights are granted separately from
44+
merge rights, because a published version cannot be taken back.
45+
46+
A port maintainer is added as an owner of their port's registry packages when:
47+
48+
- they have been a port maintainer for at least one release of that port,
49+
- their registry account has two-factor authentication turned on, and
50+
- they have walked through [docs/RELEASING.md](docs/RELEASING.md) for that registry with a core
51+
maintainer.
52+
53+
Publish rights cover the packages of that port only. A port maintainer publishes as part of a
54+
release the core maintainers have approved (see "Releases" below). The registry owners for each
55+
package are listed in [MAINTAINERS.md](MAINTAINERS.md), and that list is updated in the same
56+
change that grants or removes access.
57+
58+
### Becoming a core maintainer
59+
60+
A port maintainer can become a core maintainer after at least 6 months in that role, by
61+
invitation from the existing core maintainers. All existing core maintainers must agree.
62+
63+
## How decisions are made
64+
65+
### Lazy consensus
66+
67+
Most decisions are made by lazy consensus. A proposal is made in public, as an issue, a pull
68+
request or a discussion. If no maintainer of the affected area objects within the waiting period,
69+
it is accepted.
70+
71+
- A pull request inside one area can merge once a maintainer of that area approves it and the
72+
required checks pass. There is no fixed waiting period for these.
73+
- A change that touches more than one area waits at least 3 days after it is ready for review,
74+
so the maintainers of each area can look at it.
75+
- A maintainer does not approve their own pull request. Another maintainer of the area, or a
76+
core maintainer, reviews it. While the project has a single maintainer, that maintainer merges
77+
their own changes; this rule applies to an area once it has a second maintainer.
78+
- An objection must give a reason and, where possible, say what would resolve it. An objection
79+
without a reason does not block.
80+
81+
If the people involved cannot agree, the core maintainers decide by majority. If the core
82+
maintainers are split evenly, the creator breaks the tie only on the model format, ADRs and
83+
releases (see below). On any other subject, an even split leaves the proposal unaccepted and the
84+
status quo stands.
85+
86+
### Changes that need a core maintainer
87+
88+
These changes need explicit approval from a core maintainer, even when they sit inside one
89+
area:
90+
91+
- **The model format.** Metamodel types, subtypes and attributes; the canonical serialized form;
92+
`expected-registry.json` and `metamodelVersion`; and the shared conformance corpora under
93+
[`fixtures/`](fixtures/). These are the contract every port has to match.
94+
- **ADRs.** A new or amended decision record under [`spec/decisions/`](spec/decisions/).
95+
- **The [compatibility policy](docs/compatibility-policy.md).**
96+
- **Releases**, described next.
97+
- **This file.**
98+
99+
### Releases
100+
101+
The core maintainers decide when a release happens, what version it carries, and what goes in
102+
it. The procedure is [docs/RELEASING.md](docs/RELEASING.md). Port maintainers with publish rights
103+
run the publish for their port inside that decision. They do not publish a version the core
104+
maintainers have not approved.
105+
106+
### The creator's tie-break and veto
107+
108+
The creator, Doug Mealing, has two extra powers, limited to three subjects: the model format,
109+
ADRs and releases.
110+
111+
- **Tie-break.** When the core maintainers are split evenly on one of these subjects, the
112+
creator decides.
113+
- **Veto.** The creator can block a change to one of these subjects. A veto is written on the
114+
issue or pull request with the reason.
115+
116+
Outside those three subjects, the creator has one vote like any other core maintainer.
117+
118+
## Ownership
119+
120+
The `metaobjectsdev` GitHub organization, the package namespaces (`@metaobjectsdev` on npm,
121+
`com.metaobjects` on Maven Central, `metaobjects` on PyPI, and the `MetaObjects` packages on
122+
NuGet), the `metaobjects.dev` and `metaobjects.com` domains, and the MetaObjects name and
123+
trademark belong to Doug Mealing LLC. Roles in this file grant access to these. They do not
124+
transfer ownership.
125+
126+
The code is licensed under the [Apache License 2.0](LICENSE). Contributors keep the copyright to
127+
their contributions and license them to the project under that license. There is no copyright
128+
assignment and no contributor license agreement. Anyone may fork the code under the license; the
129+
license does not grant use of the MetaObjects name or trademark.
130+
131+
Paid work or sponsorship does not grant a role, a vote or an exception to review. A change built
132+
for a paying customer goes through the same review as any other change.
133+
134+
## Succession
135+
136+
The creator has stepped away when they say so in writing, or when they have not committed,
137+
reviewed or answered on the project for 6 months.
138+
139+
When that happens:
140+
141+
1. The remaining core maintainers run the project and decide by majority vote. The creator's
142+
tie-break does not pass to anyone, so an even split leaves the proposal unaccepted and the
143+
status quo stands.
144+
2. Doug Mealing LLC gives the remaining core maintainers admin access to the GitHub organization
145+
and owner access to every registry package, so that releases can continue.
146+
3. If there is no other core maintainer, the port maintainers choose one or more of themselves as
147+
core maintainers by majority vote, and step 2 applies to them.
148+
4. If there are no maintainers at all, the README is updated to say the project is unmaintained.
149+
The code stays available under the Apache License 2.0.
150+
151+
Ownership of the organization, the namespaces and the trademark stays with Doug Mealing LLC
152+
throughout. The creator's veto does not pass to anyone.
153+
154+
## Stepping down and removal
155+
156+
### Stepping down
157+
158+
Any maintainer can step down at any time by opening a pull request that moves them to the
159+
Emeritus section of [MAINTAINERS.md](MAINTAINERS.md). Their write access and registry ownership
160+
are removed within one week.
161+
162+
### Inactivity
163+
164+
A maintainer who has not reviewed, merged or committed in their area for 6 months is asked
165+
whether they want to stay. If they do not answer within one month, they move to Emeritus. They
166+
can come back by asking; a core maintainer restores the role unless there is a reason not to.
167+
168+
### Removal
169+
170+
A maintainer can be removed for a breach of the [Code of Conduct](CODE_OF_CONDUCT.md), or for
171+
misusing their rights, such as publishing a version outside an approved release or merging a
172+
model-format change without core-maintainer approval. The core maintainers decide by majority,
173+
not counting the person concerned. The person is told the reason directly, and the change to
174+
[MAINTAINERS.md](MAINTAINERS.md) is made in a pull request.
175+
176+
If a registry account or repository access may be compromised, any core maintainer can suspend
177+
that access at once. The decision on whether to restore it is made within two weeks.
178+
179+
## Changing this file
180+
181+
Changes to this file go through a pull request, stay open for at least 2 weeks, and need
182+
approval from every core maintainer. The Ownership section can change only with Doug Mealing
183+
LLC's agreement.
184+
185+
## Related files
186+
187+
- [MAINTAINERS.md](MAINTAINERS.md): who holds each role and each registry package today
188+
- [CONTRIBUTING.md](CONTRIBUTING.md): how to propose a change
189+
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
190+
- [SECURITY.md](SECURITY.md): how to report a vulnerability

‎MAINTAINERS.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Maintainers
2+
3+
This file lists who holds each role in the project and who owns each registry package today.
4+
[GOVERNANCE.md](GOVERNANCE.md) defines the roles and how they are earned. A change to this file
5+
goes through a pull request like any other change.
6+
7+
## Core maintainers
8+
9+
| Name | GitHub | Contact |
10+
|---|---|---|
11+
| Doug Mealing (creator) | [`dmealing`](https://github.com/dmealing) | doug@dougmealing.com |
12+
13+
The creator is the only maintainer today and covers every area below until it has a port
14+
maintainer. Every area is open.
15+
16+
## Areas
17+
18+
| Area | Paths | Port maintainer |
19+
|---|---|---|
20+
| TypeScript server port (loader, codegen, runtime, migrations, CLI) | `server/typescript/` | Maintainer wanted |
21+
| Web client (React, TanStack, Angular, framework-agnostic core) | `client/web/` | Maintainer wanted |
22+
| Java port (loader, OMDB, render, Spring codegen, Maven plugin) | `server/java/` except the Kotlin modules | Maintainer wanted |
23+
| Kotlin port | `server/java/codegen-kotlin/`, `server/java/metadata-ktx/`, `server/java/omdb-ktx/` | Maintainer wanted |
24+
| C# port | `server/csharp/` | Maintainer wanted |
25+
| Python port | `server/python/` | Maintainer wanted |
26+
| Metamodel spec and conformance corpora (core-maintainer approval always applies) | `spec/`, `fixtures/` | Maintainer wanted |
27+
| Documentation and the docs-site generator | `docs/`, `server/typescript/packages/docs-site/` | Maintainer wanted |
28+
| Libraries (`ai`, `iam`) | `library/` | Maintainer wanted |
29+
| Agent context (skills, `AGENTS.md` sources, `llms.txt`) | `agent-context/` | Maintainer wanted |
30+
| CI and release tooling | `scripts/`, `.github/` | Maintainer wanted |
31+
32+
A new generator family (for example Prisma or Django) can become its own area once someone
33+
maintains it.
34+
35+
## Registry owners
36+
37+
As of 2026-10-28, every registry package has a single owner, the creator.
38+
39+
| Registry | Packages | Owner today | How it is published |
40+
|---|---|---|---|
41+
| npm | The 14 `@metaobjectsdev/*` packages: `ai-runtime`, `cli`, `codegen-ts`, `codegen-ts-react`, `codegen-ts-tanstack`, `docs-site`, `metadata`, `migrate-ts`, `react`, `render`, `runtime-ts`, `runtime-web`, `sdk`, `tanstack` | npm user `dougmealing`, the only owner of each package, in the `metaobjectsdev` npm organization | Locally, by the release script ([docs/RELEASING.md](docs/RELEASING.md)) |
42+
| Maven Central | The `com.metaobjects` namespace: the `metaobjects` parent POM and 14 modules (`metaobjects-metadata`, `-codegen-base`, `-codegen-mustache`, `-codegen-spring`, `-codegen-kotlin`, `-codegen-plantuml`, `-render`, `-metadata-ktx`, `-maven-plugin`, `-core-spring`, `-spring-boot-starter`, `-om`, `-omdb`, `-omdb-ktx`) | The creator's Sonatype Central Portal account, which holds the verified namespace; artifacts are signed with the creator's GPG key | Locally, with `mvn deploy` |
43+
| NuGet | `MetaObjects`, `MetaObjects.Render`, `MetaObjects.Codegen`, `MetaObjects.Cli` | nuget.org organization `metaobjects`, administered by the creator | Trusted Publishing from `.github/workflows/publish-csharp.yml` |
44+
| PyPI | `metaobjects` | PyPI user `dougmealing` (Owner) | Locally or from `.github/workflows/publish-python.yml` with an API token |
45+
46+
`@metaobjectsdev/angular` and `@metaobjectsdev/codegen-ts-angular` are source-only and are not on
47+
npm ([ADR-0048](spec/decisions/ADR-0048-angular-tier-source-only.md)).
48+
49+
The `metaobjectsdev` GitHub organization has one member and owner, `dmealing`.
50+
51+
## Emeritus
52+
53+
None yet.

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -355,6 +355,12 @@ named-constants-for-metamodel-strings, no-`any` rule, cross-language porting
355355
contract, public-repo hygiene). For significant new features, open an issue
356356
first to discuss the approach.
357357

358+
[`GOVERNANCE.md`](GOVERNANCE.md) sets out the roles (contributor, port maintainer, core
359+
maintainer), how merge and publish rights are earned, how decisions are made, and what
360+
happens if the creator steps away. [`MAINTAINERS.md`](MAINTAINERS.md) lists who maintains
361+
each port and area today, and who owns each registry package. Every port is looking for a
362+
maintainer.
363+
358364
## Roadmap
359365

360366
Current + planned work is tracked as [GitHub issues labelled `FR`](https://github.com/metaobjectsdev/metaobjects/issues?q=is%3Aissue+label%3AFR), with [milestones](https://github.com/metaobjectsdev/metaobjects/milestones) for releases. [`spec/roadmap.md`](spec/roadmap.md) holds the release direction and the index of feature specs.

0 commit comments

Comments
 (0)