tegwick
235355eb58
Navigation: - New order: Overview · Todo · Domains · Repos · Workstreams (collapsible, open:false, with atomic sub-entries: Decisions, Tasks, Debt, Extends, Dependencies) · Contributions · SBOM · Progress · Reference (collapsible) - Reference section gains path:/reference landing page; all 18 doc pages listed in nav (alphabetical) and in reference.md table New pages: - todo.md — Internal / Ecosystem / Third-party todo classification - dependencies.md — dependency edge table derived from state/summary - reference.md — Reference landing page with full doc index New reference doc pages (11): contributions, debt, dependencies, domains, extensions, overview, repos, tasks, todo + reference (meta) already added previously doc-overlay.js — lazy bubblehelp tooltip: - _titleCache Map + _fetchDocTitle(docPath): on first hover of any ? button, fetches the target doc page, parses <h1>, sets btn.title - Native browser tooltip appears exactly on the ? circle on subsequent hover Context-help wired on all 14 dashboard pages: - h1 withDocHelp added to: index, todo, domains, repos, tasks, techdept, extensions, dependencies (contributions/workstreams/decisions/sbom/ progress/reference were already wired) - domains.md + repos.md: added missing withDocHelp import and live-data link - tasks/techdept/extensions: removed duplicate _h1 const that caused SyntaxError: Identifier '_h1' has already been declared Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.8 KiB
title
| 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 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.