121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
|
---
|
||
|
|
title: Contributions — Reference
|
||
|
|
---
|
||
|
|
|
||
|
|
# Contributions — Reference
|
||
|
|
|
||
|
|
Contributions track **outbound upstream work** — things the Custodian has
|
||
|
|
identified that belong in a repo it does not own or control. Each contribution
|
||
|
|
is a structured artifact filed locally in the repo's `contrib/` directory and
|
||
|
|
registered in the state hub so it is never lost.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Contribution types
|
||
|
|
|
||
|
|
| Type | Full name | Use when |
|
||
|
|
|------|-----------|----------|
|
||
|
|
| `br` | Bug Report | You found a defect in an upstream tool or library |
|
||
|
|
| `fr` | Feature Request | You need functionality that upstream does not yet provide |
|
||
|
|
| `ep` | Extension Point | You identified a future enhancement opportunity in upstream code |
|
||
|
|
| `upr` | Upstream PR | You have written (or are writing) a patch for an upstream repo |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Lifecycle
|
||
|
|
|
||
|
|
```
|
||
|
|
draft → submitted → acknowledged → accepted → merged
|
||
|
|
↘ ↘
|
||
|
|
rejected withdrawn
|
||
|
|
```
|
||
|
|
|
||
|
|
| Status | Meaning |
|
||
|
|
|--------|---------|
|
||
|
|
| **draft** | Artifact written locally; not yet sent upstream |
|
||
|
|
| **submitted** | Filed as a GitHub issue, PR, or email — awaiting upstream response |
|
||
|
|
| **acknowledged** | Upstream has seen it and responded (e.g. triaged, commented) |
|
||
|
|
| **accepted** | Upstream agreed to take action |
|
||
|
|
| **merged** | PR accepted and merged; issue resolved |
|
||
|
|
| **rejected** | Upstream declined; record kept for future reference |
|
||
|
|
| **withdrawn** | We decided not to pursue it |
|
||
|
|
|
||
|
|
Transitions are enforced by the API — you cannot skip stages arbitrarily.
|
||
|
|
`submitted_at` is stamped automatically when status moves to `submitted`;
|
||
|
|
`resolved_at` is stamped when status moves to `merged`, `rejected`, or `withdrawn`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Relation to the Todo classification
|
||
|
|
|
||
|
|
Contributions map directly to the **Third-party** class in the inter-repo
|
||
|
|
communication taxonomy:
|
||
|
|
|
||
|
|
| Todo class | Mechanism |
|
||
|
|
|------------|-----------|
|
||
|
|
| Internal | Workplan file + task in this repo's workstream |
|
||
|
|
| Ecosystem | State hub task with `[repo:<slug>]` prefix |
|
||
|
|
| **Third-party** | **Contribution artifact in `contrib/` + state hub registration** |
|
||
|
|
|
||
|
|
Contributions in `draft`, `submitted`, or `acknowledged` status appear as
|
||
|
|
open Third-party todos on the [Todo](/todo) page.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## File layout
|
||
|
|
|
||
|
|
Each artifact lives in the current repo under `contrib/`:
|
||
|
|
|
||
|
|
```
|
||
|
|
contrib/
|
||
|
|
bug-reports/ br-YYYY-MM-DD--<org>--<repo>--<slug>.md
|
||
|
|
feature-requests/ fr-YYYY-MM-DD--<org>--<repo>--<slug>.md
|
||
|
|
extension-points/ EP-<DOMAIN>-NNN--<org>--<repo>--<slug>.md
|
||
|
|
upstream-prs/ upr-YYYY-MM-DD--<org>--<repo>--<slug>.md
|
||
|
|
```
|
||
|
|
|
||
|
|
Templates live in `~/the-custodian/canon/standards/contrib-templates/`.
|
||
|
|
Convention details: `~/the-custodian/canon/standards/contribution-convention_v0.1.md`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Adding a contribution
|
||
|
|
|
||
|
|
**1. Write the artifact file** using the appropriate template.
|
||
|
|
|
||
|
|
**2. Register it in the state hub** via MCP:
|
||
|
|
|
||
|
|
```
|
||
|
|
register_contribution(
|
||
|
|
type = "fr",
|
||
|
|
title = "Add sidebar TOC injection API",
|
||
|
|
target_org = "observablehq",
|
||
|
|
target_repo = "framework",
|
||
|
|
body_path = "contrib/feature-requests/fr-2026-02-26--observablehq--framework--toc.md",
|
||
|
|
related_workstream_id = "<uuid>"
|
||
|
|
)
|
||
|
|
```
|
||
|
|
|
||
|
|
**3. Close the loop** when you file it upstream:
|
||
|
|
|
||
|
|
```
|
||
|
|
update_contribution_status(contribution_id="<uuid>", status="submitted")
|
||
|
|
```
|
||
|
|
|
||
|
|
**4. Keep updating** as upstream responds — `acknowledged`, `accepted`, `merged`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Kanban board
|
||
|
|
|
||
|
|
The Contributions page groups artifacts by status column. Only columns with at
|
||
|
|
least one entry are shown. The **⚠ follow-up banner** appears when any
|
||
|
|
contribution has been in `submitted` or `acknowledged` for an extended period
|
||
|
|
without further movement — a prompt to check in with upstream.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
*Contributions are append-only. Rejected or withdrawn artifacts are retained as
|
||
|
|
institutional memory — they explain why certain approaches were tried and
|
||
|
|
dropped.*
|