feat(dashboard): nav restructure, full context-help coverage, 11 new ref docs
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>
This commit is contained in:
120
state-hub/dashboard/src/docs/contributions.md
Normal file
120
state-hub/dashboard/src/docs/contributions.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
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.*
|
||||
Reference in New Issue
Block a user