tegwick
0d978b1417
- canon/standards/contribution-convention_v0.1.md: master spec for BR/FR/EP/UPR artifact types, directory layout, frontmatter schema, ID schemes (EP-DOMAIN-NNN for extension points), status lifecycle, and relationship to State Hub - canon/standards/contrib-templates/: four template files (br, fr, ep, upr) - contrib/upstream-prs/2026-02-26--observablehq--framework--toc-sidebar-inject.md: first real UPR artifact — proposes injectTocTop() to Observable Framework Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
158 lines
5.0 KiB
Markdown
158 lines
5.0 KiB
Markdown
---
|
|
id: canon-contrib-convention
|
|
type: standard
|
|
title: "Contribution Convention v0.1"
|
|
domain: custodian
|
|
status: active
|
|
version: "0.1"
|
|
created: "2026-02-28"
|
|
---
|
|
|
|
# Contribution Convention v0.1
|
|
|
|
## Purpose
|
|
|
|
This document defines the canonical convention for tracking upstream contributions
|
|
across all custodian-ecosystem repositories. A *contribution* is any intentional
|
|
engagement with an external upstream project: a bug report, feature request,
|
|
extension-point proposal, or pull request.
|
|
|
|
Contributions are tracked as Markdown artifacts with typed YAML frontmatter,
|
|
committed to the repository that authors them, and indexed in the State Hub DB.
|
|
This enables the Custodian to maintain a full audit trail of all upstream
|
|
engagement across all six project domains.
|
|
|
|
## Artifact Types
|
|
|
|
| Code | Name | Description |
|
|
|------|------|-------------|
|
|
| `br` | Bug Report | A defect reported to an upstream project |
|
|
| `fr` | Feature Request | A capability requested from an upstream project |
|
|
| `ep` | Extension-Point Proposal | A proposed extension point in an upstream project |
|
|
| `upr`| Upstream PR | A pull request submitted or planned for upstream |
|
|
|
|
## Directory Layout
|
|
|
|
```
|
|
<repo-root>/
|
|
contrib/
|
|
bug-reports/ # BR artifacts
|
|
feature-requests/ # FR artifacts
|
|
extension-points/ # EP artifacts
|
|
upstream-prs/ # UPR artifacts
|
|
```
|
|
|
|
Each artifact file follows the naming pattern:
|
|
|
|
```
|
|
<YYYY-MM-DD>--<org>--<repo>--<slug>.md
|
|
```
|
|
|
|
Examples:
|
|
- `contrib/bug-reports/2026-03-01--observablehq--framework--plot-tooltip-flicker.md`
|
|
- `contrib/upstream-prs/2026-02-26--observablehq--framework--toc-sidebar-inject.md`
|
|
- `contrib/extension-points/EP-CUST-002--anthropic--claude-code--hook-on-tool-result.md`
|
|
|
|
## Frontmatter Schema
|
|
|
|
All contribution artifacts share a common base frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
id: <type>-<YYYY-MM-DD>--<org>--<repo>--<slug> # unique string ID
|
|
type: br | fr | ep | upr # required
|
|
target_org: <github-org-or-owner> # required
|
|
target_repo: <repository-name> # required
|
|
title: "Human-readable title" # required
|
|
status: draft | submitted | acknowledged | accepted | rejected | merged | withdrawn
|
|
domain: custodian | railiance | markitect | ... # originating domain
|
|
related_workstream: <workstream-slug> # optional
|
|
state_hub_contribution_id: <uuid> # set once registered in State Hub
|
|
created: "YYYY-MM-DD"
|
|
updated: "YYYY-MM-DD"
|
|
---
|
|
```
|
|
|
|
### BR — Bug Report (additional fields)
|
|
|
|
```yaml
|
|
upstream_version: "1.2.3" # version where bug was observed
|
|
reproduction_steps: |
|
|
1. …
|
|
2. …
|
|
expected: "What should happen"
|
|
actual: "What actually happens"
|
|
workaround: "Any known workaround" # optional
|
|
upstream_issue_url: "https://…" # optional — link once filed
|
|
```
|
|
|
|
### FR — Feature Request (additional fields)
|
|
|
|
```yaml
|
|
motivation: "Why this feature is needed"
|
|
proposed_api: |
|
|
# Sketch of the proposed interface
|
|
alternatives: "What we do instead today"
|
|
upstream_issue_url: "https://…" # optional
|
|
```
|
|
|
|
### EP — Extension-Point Proposal (additional fields)
|
|
|
|
```yaml
|
|
ep_id: EP-<DOMAIN>-NNN # e.g. EP-RAIL-007
|
|
location: "src/file.ts:42" # file:line in upstream where hook would live
|
|
proposed_interface: |
|
|
# Interface or callback signature sketch
|
|
rationale: "Why this extension point is valuable"
|
|
upstream_issue_url: "https://…" # optional
|
|
```
|
|
|
|
### UPR — Upstream PR (additional fields)
|
|
|
|
```yaml
|
|
local_component_path: "relative/path/in/this/repo"
|
|
target_upstream_file: "path/in/upstream/repo"
|
|
upstream_pr_url: "https://…" # set once submitted
|
|
draft_pr_body: |
|
|
## Summary
|
|
…
|
|
|
|
## Motivation
|
|
…
|
|
```
|
|
|
|
## ID Schemes
|
|
|
|
- **BR / FR / UPR**: `<type>-<YYYY-MM-DD>--<org>--<repo>--<slug>` — date-prefixed slug
|
|
- **EP**: `EP-<DOMAIN>-NNN` where `<DOMAIN>` is uppercase (CUST, RAIL, MARK, etc.)
|
|
and `NNN` is a zero-padded three-digit sequence per domain (EP-CUST-001,
|
|
EP-CUST-002, …). This scheme is an extension of the Railiance EP convention
|
|
defined in the staged-promotion-lifecycle workstream; this canon document is
|
|
the authoritative master spec.
|
|
|
|
## Status Lifecycle
|
|
|
|
```
|
|
draft → submitted → acknowledged → accepted → merged
|
|
↘ ↘
|
|
rejected withdrawn
|
|
```
|
|
|
|
- `draft`: artifact created locally, not yet sent upstream
|
|
- `submitted`: issue filed or PR opened upstream
|
|
- `acknowledged`: upstream team has responded
|
|
- `accepted`: upstream has agreed to the proposal
|
|
- `rejected`: upstream has declined
|
|
- `merged`: PR merged / fix released
|
|
- `withdrawn`: we decided not to pursue
|
|
|
|
## Relationship to State Hub
|
|
|
|
Once an artifact is registered via `register_contribution()` MCP tool or
|
|
`POST /contributions/` API, the State Hub assigns a UUID and returns it.
|
|
That UUID is written back into `state_hub_contribution_id` in the frontmatter.
|
|
|
|
The State Hub is a **read/cache layer** — the Markdown file is always the
|
|
authoritative source of truth. If the DB is reset, contributions can be
|
|
re-ingested from the files.
|