---
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.*