This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 4c53b68 docs(contributor-growth): add family README with stage
coverage and adopter contract (#576)
4c53b68 is described below
commit 4c53b6872ed1740ac036e7dcc01245b32abd84e9
Author: Justin Mclean <[email protected]>
AuthorDate: Sat Jun 27 20:09:35 2026 +1000
docs(contributor-growth): add family README with stage coverage and adopter
contract (#576)
Documents the five contributor-growth skills (mentoring-welcome,
contributor-activity-sweep, contributor-nomination, good-first-issue-author,
committer-onboarding) with their stage coverage table, mode assignments,
family boundary, and per-skill adopter-config file mapping.
Follows the pattern of docs/issue-management/README.md and
docs/pr-management/README.md. The spec for this family lands separately
(contributor-growth-spec PR #564); this human-facing docs directory is the
companion that makes the adopter contract navigable without reading the
spec.
Generated-by: Claude (Opus 4.7)
---
docs/contributor-growth/README.md | 126 ++++++++++++++++++++++++++++++++++++++
1 file changed, 126 insertions(+)
diff --git a/docs/contributor-growth/README.md
b/docs/contributor-growth/README.md
new file mode 100644
index 0000000..5e6990d
--- /dev/null
+++ b/docs/contributor-growth/README.md
@@ -0,0 +1,126 @@
+<!-- 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)*
+
+- [Contributor-growth skill family](#contributor-growth-skill-family)
+ - [Stage coverage](#stage-coverage)
+ - [Skills](#skills)
+ - [Family boundary](#family-boundary)
+ - [Adopter contract](#adopter-contract)
+ - [Status](#status)
+ - [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 -->
+
+# Contributor-growth skill family
+
+Maintainer-facing skills that span the contributor-to-committer path:
+welcoming first-time contributors, keeping the issue backlog newcomer-
+ready, tracking contribution activity, assembling nomination evidence,
+and walking nominators through post-vote onboarding. Five skills cover
+the staged path from first contact through committer promotion.
+
+Why a framework skill family? The contributor-to-committer path is one
+of the highest-leverage levers an open-source project has for long-term
+health — lowering onboarding friction and shortening the time from first
+PR to committer status keeps the contributor pipeline healthy. These
+skills were designed independently but cover a contiguous path; grouping
+them makes the adopter configuration and the evaluation story coherent.
+
+## Stage coverage
+
+| Stage | Skill | What it does |
+|---|---|---|
+| **First contact** |
[`mentoring-welcome`](../../skills/mentoring-welcome/SKILL.md) | Drafts an
orientation comment for a first-time contributor on a newly opened issue or PR;
detects first-time authorship via the GitHub `author_association` field and
skips repeat contributors. |
+| **Issue on-ramp** |
[`good-first-issue-author`](../../skills/good-first-issue-author/SKILL.md) |
Drafts one net-new good first issue from a supplied gap or small task; a
suitability gate and R1–R9 readiness checklist gate the draft; waits for
maintainer confirmation before filing via `gh`. |
+| **Activity tracking** |
[`contributor-activity-sweep`](../../skills/contributor-activity-sweep/SKILL.md)
| Produces a read-only GitHub activity card (PRs authored, code reviews,
issues, comments) over a configurable window. |
+| **Nomination brief** |
[`contributor-nomination`](../../skills/contributor-nomination/SKILL.md) |
Assembles evidence prose for a committer or PMC vote thread: activity breadth,
consistency, vendor-neutrality context, and a nomination-ready summary.
Read-only; never posts to any list. |
+| **Post-vote onboarding** |
[`committer-onboarding`](../../skills/committer-onboarding/SKILL.md) | Walks
the nominator through ICLA check, account provisioning, permissions grant, and
the welcome announcement for committer and PMC promotions at ASF TLPs and
podlings. |
+
+Every stage is read-only on governance artefacts or propose-before-post:
+no skill modifies a roster, posts an announcement, or files an issue
+without explicit maintainer confirmation.
+
+## Skills
+
+| Skill | Mode | Status |
+|---|---|---|
+| [`mentoring-welcome`](../../skills/mentoring-welcome/SKILL.md) | Mentoring |
experimental |
+| [`good-first-issue-author`](../../skills/good-first-issue-author/SKILL.md) |
Mentoring | experimental |
+|
[`contributor-activity-sweep`](../../skills/contributor-activity-sweep/SKILL.md)
| Triage | experimental |
+| [`contributor-nomination`](../../skills/contributor-nomination/SKILL.md) |
Triage | experimental |
+| [`committer-onboarding`](../../skills/committer-onboarding/SKILL.md) |
Triage | experimental |
+
+All five skills are `experimental`; no adopter has run the full
+contributor-to-committer path under evaluation conditions yet.
+
+## Family boundary
+
+This family sits **alongside** two overlapping skill families:
+
+- [`docs/mentoring/README.md`](../mentoring/README.md) — the Mentoring
+ mode spec and family overview. `mentoring-welcome` and
+ `good-first-issue-author` carry `mode: Mentoring` and are also
+ listed in that spec. The families cross-reference each other; a later
+ maturity review may clarify the boundary or merge the two into one.
+- [`docs/issue-management/README.md`](../issue-management/README.md) —
+ general-issue triage and fix workflow. The contributor-growth family
+ reads GitHub activity data about contributors, not issue content; the
+ two families use different query surfaces and produce different
+ artefacts (activity cards and nomination briefs vs. issue disposition
+ proposals).
+
+Skills in this family propose every state-changing action for human
+sign-off. `committer-onboarding` emits paste-ready command recipes the
+nominator executes as themselves; no skill submits an ICLA form, invites
+an account, or modifies repository permissions without the nominator's
+direct action.
+
+## Adopter contract
+
+The skills resolve project-specific content from these files in the
+adopter's `<project-config>/` directory:
+
+| File | Used by |
+|---|---|
+| [`project.md`](../../projects/_template/project.md) | all skills (upstream
repo slug, GitHub token context, `<tracker>` reference) |
+| [`pmc-roster.md`](../../projects/_template/pmc-roster.md) |
`contributor-nomination`, `committer-onboarding` (PMC and committer rosters,
ICLA-checker URL) |
+|
[`contributor-nomination-config.md`](../../projects/_template/contributor-nomination-config.md)
| `contributor-nomination` (activity-window length, committer / PMC
thresholds, required-areas gates) |
+|
[`mentoring-welcome-config.md`](../../projects/_template/mentoring-welcome-config.md)
| `mentoring-welcome` (tone knobs, contributing-doc links, AI-attribution
footer wording) |
+|
[`good-first-issue-config.md`](../../projects/_template/good-first-issue-config.md)
| `good-first-issue-author` (issue-tracker URL, getting-started link,
out-of-scope topic list) |
+
+## Status
+
+**Experimental.** All five skills are on main with eval suites; no
+adopter has run the full contributor-to-committer path end-to-end under
+evaluation conditions.
+
+Known deferred items (each pending a spec-RFC pass that enumerates
+per-project policy knobs before a skill can safely propose anything):
+
+- **PMC-member nomination** — vote mechanics, quorum rules, and
+ post-vote steps differ from committer promotion and warrant a
+ separate capability-flag variant of `committer-onboarding` or a
+ standalone skill.
+- **Emeritus / inactive-committer handling and contributor offboarding**
+ — these involve project-level governance decisions (roster policy,
+ access removal, farewell communication norms) that need per-project
+ configuration.
+
+## Cross-references
+
+- [`docs/modes.md` § Triage](../modes.md#triage) — mode taxonomy the
+ three Triage-mode family skills declare against.
+- [`docs/modes.md` § Mentoring](../modes.md#mentoring) — mode taxonomy
+ the two Mentoring-mode family skills declare against.
+- [`docs/mentoring/README.md`](../mentoring/README.md) — the Mentoring
+ mode family overview, which cross-references `mentoring-welcome` and
+ `good-first-issue-author`.
+- [`projects/_template/README.md`](../../projects/_template/README.md) —
+ adopter scaffold index, including the three contributor-growth config
+ templates listed in the Adopter contract above.
+- [`docs/setup/agentic-overrides.md`](../setup/agentic-overrides.md) —
+ the override mechanism every skill in this family supports.
