Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
253 changes: 253 additions & 0 deletions .apache-magpie-overrides/committer-onboarding-config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,253 @@
<!-- SPDX-License-Identifier: Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0 -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Apache Magpie — committer-onboarding configuration](#apache-magpie--committer-onboarding-configuration)
- [Intake model](#intake-model)
- [Intake-model-specific keys](#intake-model-specific-keys)
- [Governance model](#governance-model)
- [Governance-model-specific keys](#governance-model-specific-keys)
- [Cross-references](#cross-references)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<!-- SPDX-License-Identifier: Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0 -->

# Apache Magpie — committer-onboarding configuration

**This file enumerates the capability-flag vocabulary for the
`committer-onboarding` skill.** It is the contributor-growth
counterpart to `release-management-config.md`'s backend-flag model:
an adopter declares the intake and governance model that suits their
community, and the skill emits onboarding steps shaped for that model,
without any skill-body edit.

**Currently the `committer-onboarding` skill defaults to the ASF-PMC
/ ICLA model** (the ASF default). This file establishes the flag
vocabulary so that a non-ASF adopter can declare their model here;
the skill will read these flags in a follow-on update. New adopters
should copy this file into their own
`<project-config>/committer-onboarding-config.md` and replace every
`TODO`.

Related scaffolds in the same adopter directory:

- `committer-readiness.md` — activity thresholds the
`contributor-to-committer` readiness tracker compares against
(added by the `contributor-to-committer` skill).
- [`contributor-nomination-config.md`](contributor-nomination-config.md)
— nomination-brief thresholds and assessment window.
- [`pmc-roster.md`](pmc-roster.md) — PMC-member roster used by
`release-vote-tally` to classify binding vs non-binding votes.

---

## Intake model

Declares how new committers are formally onboarded to the project's
IP policy after a vote passes.

```yaml
committer_intake:
# Model under which new committers are formally onboarded to the
# project's IP policy.
# ASF default: icla — every new committer must file a signed ICLA
# with the Apache Software Foundation before commit bits are
# granted. The skill checks Whimsy and blocks the account-request
# step if no ICLA is on file.
# Override when:
# dco — Developer Certificate of Origin (Linux Foundation model).
# A per-commit `Signed-off-by:` line replaces the one-time CLA;
# the skill links the DCO guide and verifies that the candidate's
# recent merged PRs carry sign-off.
# no-cla — No formal contributor agreement required (open/trust-
# based model). The skill skips IP-check steps entirely.
# Allowed values: icla, dco, no-cla
# Consumed by: committer-onboarding (intake-check step).
model: icla # icla | dco | no-cla
```

### Intake-model-specific keys

Fill in only the block that matches your `model` above; leave the
others absent or blank.

#### `icla` model

```yaml
committer_intake_icla:
# URL the skill links when asking the nominator to check the
# candidate's ICLA status.
# ASF default: Whimsy's committer lookup.
# Non-ASF adopters using ICLA: point at your foundation's CLA
# query endpoint.
# Consumed by: committer-onboarding.
lookup_url: https://whimsy.apache.org/roster/committer/

# Whether ICLA filing is a hard prerequisite that the skill refuses
# to bypass. When true, the skill blocks until the nominator
# confirms the ICLA is on file; when false, the skill flags the
# gap but allows the nominator to proceed with a warning.
# ASF default: true.
# Consumed by: committer-onboarding.
mandatory: true
```

#### `dco` model

```yaml
committer_intake_dco:
# Reference URL the skill links in onboarding communications
# explaining what DCO sign-off means for contributors.
# Linux Foundation / CNCF projects typically link
# https://developercertificate.org/ plus their own CONTRIBUTING.md.
# Consumed by: committer-onboarding.
reference_url: null # not used — Apache Magpie uses the icla model

# Minimum number of the candidate's recently merged PRs that must
# carry a valid `Signed-off-by:` line before the skill considers
# the DCO check passed.
# Set to 0 to skip the check (honour-system model).
# Consumed by: committer-onboarding.
min_signed_off_prs: 1
```

#### `no-cla` model

```yaml
committer_intake_nocla:
# Free-text explanation shown in the onboarding checklist in place
# of an IP-agreement check. Leave null for a default message.
# Consumed by: committer-onboarding.
explanation: null
# e.g. "This project uses an Apache-2.0 inbound/outbound model; no
# CLA or DCO sign-off is required — contributors retain copyright."
```

---

## Governance model

Declares how committer and PMC (or equivalent) status is formally
tracked, voted on, and applied after a vote passes.

```yaml
committer_governance:
# Model under which committer and committee status is granted and
# tracked.
# ASF default: asf-pmc — the PMC votes on the dev@ list, submits a
# secretary account-creation request via Whimsy, and the new
# committer appears on the Apache Whimsy committee/committer roster.
# Override when:
# github-codeowners — CODEOWNERS file + GitHub maintainer-team
# membership drives merge permissions; no formal committee vote
# and no external account-creation request.
# maintainer-roster — an adopter-managed roster file voted on by
# existing maintainers, outside any foundation's governance
# machinery.
# Allowed values: asf-pmc, github-codeowners, maintainer-roster
# Consumed by: committer-onboarding (roster-management steps).
model: asf-pmc # asf-pmc | github-codeowners | maintainer-roster
```

### Governance-model-specific keys

Fill in only the block that matches your `model` above.

#### `asf-pmc` model

```yaml
committer_governance_asf_pmc:
# Whether the project is an incubating podling or a graduated
# top-level project. This switches between Whimsy's PPMC
# self-service UI (podling) and `committee-info.txt` edits (TLP).
# Allowed values: podling, tlp
# Consumed by: committer-onboarding (roster-management path
# selection).
stage: tlp # podling | tlp

# Whimsy URL the skill links the nominator to for roster management.
# TLP default: committee detail page.
# Podling default: PPMC roster page.
# Consumed by: committer-onboarding.
whimsy_roster_url: https://whimsy.apache.org/roster/committee/magpie
# TLP example: https://whimsy.apache.org/roster/committee/<project>
# Podling example: https://whimsy.apache.org/roster/ppmc/<project>

# URL of the ASF's new-committer / new-PMC-member secretary request
# form. The skill prints this and asks the nominator to fill it in.
# ASF default: the standard secretary request page.
# Consumed by: committer-onboarding.
secretary_request_url: https://whimsy.apache.org/officers/acreq

# Dev-list address the skill uses when drafting the welcome
# announcement. Matches `dev_list` in project.md — kept here for
# self-contained configuration.
# Consumed by: committer-onboarding.
dev_list: dev@magpie.apache.org
```

#### `github-codeowners` model

```yaml
committer_governance_github_codeowners:
# GitHub team slug (in `org/team` form) that maps to the
# committer/maintainer team. The skill invites the new committer
# to this team after the vote passes.
# Consumed by: committer-onboarding.
maintainers_team: null # not used — Apache Magpie uses the asf-pmc model

# Path to the CODEOWNERS file in the upstream repo, relative to
# the repo root. The skill optionally opens a PR adding the new
# committer's handle to the file.
# Leave null to skip the CODEOWNERS update.
# Consumed by: committer-onboarding.
codeowners_file: CODEOWNERS # or null

# Whether a GitHub-discussion or a GitHub-issue thread is the
# canonical "vote thread" for this model.
# Allowed values: github-discussion, github-issue, off-band
# `off-band` = the vote happened in Slack / email / another channel
# and the skill just records the outcome.
# Consumed by: committer-onboarding (vote-validation step).
vote_channel: null # not used — asf-pmc model
```

#### `maintainer-roster` model

```yaml
committer_governance_maintainer_roster:
# Path to the roster file (relative to <project-config>/) that
# the skill updates when a vote passes.
# Consumed by: committer-onboarding.
roster_file: null # not used — asf-pmc model

# Minimum number of approvals required from existing listed
# maintainers before the skill considers the vote passed.
# Consumed by: committer-onboarding (vote-validation step).
min_approvals: null # not used — asf-pmc model

# Channel where votes are held — used by the skill when
# summarising the vote result.
# Allowed values: github-discussion, github-issue, mailing-list,
# slack-channel, off-band
# Consumed by: committer-onboarding.
vote_channel: null # not used — asf-pmc model
```

---

## Cross-references

- `committer-readiness.md` — activity thresholds for the
`contributor-to-committer` readiness tracker (added by the
`contributor-to-committer` skill).
- [`contributor-nomination-config.md`](contributor-nomination-config.md)
— nomination-brief thresholds and assessment window.
- [`pmc-roster.md`](pmc-roster.md) — PMC-member roster for vote tally.
- [`committer-onboarding`](../.agents/skills/magpie-committer-onboarding/SKILL.md)
— the skill that reads this configuration.
139 changes: 139 additions & 0 deletions .apache-magpie-overrides/committer-readiness.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
<!-- SPDX-License-Identifier: Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0 -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Apache Magpie — committer-readiness configuration](#apache-magpie--committer-readiness-configuration)
- [Assessment window](#assessment-window)
- [Committer thresholds](#committer-thresholds)
- [PMC thresholds](#pmc-thresholds)
- [Automated and low-signal contributions](#automated-and-low-signal-contributions)
- [Project expectations for AI-assisted contributions](#project-expectations-for-ai-assisted-contributions)
- [Project-specific notes *(optional)*](#project-specific-notes-optional)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<!-- SPDX-License-Identifier: Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0 -->

# Apache Magpie — committer-readiness configuration

Per-project thresholds for the
[`contributor-to-committer`](../skills/contributor-to-committer/SKILL.md)
readiness tracker. Copy into your `<project-config>/` directory and
replace every TODO.

**Thresholds are optional.** If this file does not declare thresholds,
the skill falls back to `contributor-nomination-config.md` thresholds,
or asks the maintainer at run time. Only declare thresholds here if
your PMC has agreed on explicit criteria — they vary across projects
and there are no meaningful universal defaults.

**This file is separate from `contributor-nomination-config.md`** so
that the readiness tracker and the nomination brief can be tuned
independently. If your project uses the same bar for both, you can
set this file's thresholds to the same values and keep a single place
to update them.

---

## Assessment window

| Key | Value | Notes |
|---|---|---|
| `assessment_window_months` | `6` | How many months of activity to assess. 6 is common; slower-moving projects may prefer 12. |

---

## Committer thresholds

Calibrate against recent successful nominations on your project, not
against framework defaults. The numbers below are a low bar for a
mid-size active project.

| Dimension | Default (low bar) | Project value | Notes |
|---|---|---|---|
| `prs_merged` | `5` | (default) | Merged PRs — the clearest signal of sustained code contribution |
| `reviews_total` | `3` | (default) | Total review acts — shows engagement with others' work |
| `reviews_substantive` | `2` | (default) | Reviews with real inline feedback (≥ 3 comments or > 50 char body) |
| `issues_filed` | `0` | (default) | Set to 0 to treat as non-required; many valid tracks don't involve filing issues |
| `threads_commented` | `5` | (default) | PR/issue comment threads — basic community presence |
| `area_breadth` | `0` | (default) | Distinct `area:*` labels across merged PRs; 0 = no breadth requirement |

---

## PMC thresholds

PMC membership requires demonstrated community leadership beyond code.
Raise these well above the committer bar for any project that treats
PMC as a senior track.

| Dimension | Default (low bar) | Project value | Notes |
|---|---|---|---|
| `prs_merged` | `10` | (default) | |
| `reviews_total` | `8` | (default) | PMC members are expected to help evaluate others' work |
| `reviews_substantive` | `4` | (default) | |
| `issues_filed` | `0` | (default) | |
| `threads_commented` | `10` | (default) | |
| `area_breadth` | `2` | (default) | PMC members typically span multiple project areas |

---

## Automated and low-signal contributions

How the readiness tracker discounts visibly automated or low-signal GitHub activity.
The full definition — detection heuristics, aggregation, and how the brief reports raw and adjusted counts — is [`automated-contributions.md`](../skills/contributor-nomination/automated-contributions.md).

The discount is a signal for the humans reading the brief, never an automatic disqualification.
Using AI tools, and disclosing that use, is not penalised; only restatement, content maintainers pushed back on, and work closed after that pushback are discounted.

Each key is resolved from this file first, then from `contributor-nomination-config.md`, then from the default below.

| Key | Default | Project value | Notes |
|---|---|---|---|
| `automated_contribution_weight` | `0.25` | (default) | Weight (0–1) of a merged or open PR, issue, review or comment that drew maintainer pushback as looking generated, unreviewed, restating, fabricated, or unwanted |
| `restatement_comment_weight` | `0` | (default) | Weight (0–1) of a comment or review body that only restates the description, earlier comments, or the diff |
| `closed_after_pushback_weight` | `0` | (default) | Weight (0–1) of a PR or issue closed unmerged after that pushback; `0` removes it from every metric |
| `automated_pushback_phrases` | empty | (default) | Extra phrases your maintainers use when pushing back, added to the generic list |

Set all three weights to `1` to turn the arithmetic off; flagged items are still listed in the brief.

### Project expectations for AI-assisted contributions

List the documents in which your project states what it expects from AI-assisted and automated contributions — a generative-AI contribution policy, PR guidelines, a review or triage guide.
Use paths relative to the repository root, or `https://` URLs, optionally with a `#section` anchor.

```yaml
automated_contribution_expectations:
- docs/ai-contribution-policy.md
- https://www.apache.org/legal/generative-tooling.html#include-in-contributions
- CONTRIBUTING.md#authoring-with-an-agent
```

When the list is present, the skill reads each document, judges contributions against it first, and cites the document and section each flagged item conflicts with.
When it is empty or none of the documents can be read, the skill falls back to the framework's generic heuristics and says so in the brief.
The skill does not go looking for policy documents this list does not name.

---

## Project-specific notes *(optional)*

Free text surfaced at the top of every readiness brief. Use for norms
the maintainer should see — e.g. multi-repo projects, non-GitHub
contribution tracks that are particularly valued, or cultural notes
about how the PMC calibrates nominations.

```text
Apache Magpie became a top-level project in June 2026, so contributor
histories are short: judge against the 6-month window, and do not read a
short history as a negative signal by itself.
All development happens in the single repository apache/magpie.
Most contributions are authored with a coding agent. That is expected and
neither a positive nor a negative signal; assess ownership and review quality
against docs/ai-contribution-policy.md.
Skill, eval and documentation work counts as code contribution here: the
framework is written in English as code (CONTRIBUTING.md#english-as-code).
Committer and PMC votes happen on private@magpie.apache.org.
```
Loading