Repository navigation
DX: create first-contributor fast paths #682
Copy link
Copy link
Closed
Labels
docsDocumentation changesDocumentation changesdocumentationImprovements or additions to documentationImprovements or additions to documentationenhancementNew feature or requestNew feature or requestlegend:DXDeveloper experience workDeveloper experience worklegend:PROCESSMethod/process workMethod/process workstatus: non-blockingThis issue is not a blocker for a release.This issue is not a blocker for a release.triage:requestsUnscheduled valid requests that still need a release scheduling decisionUnscheduled valid requests that still need a release scheduling decisionwork-in-progressMethod issue is actively being workedMethod issue is actively being worked
Description
Problem
The project is effectively single-author plus bot/test identities, and the docs style amplifies bus-factor risk. A new external contributor needs narrow, non-philosophical entry paths.
Evidence at e948217274fe:
git shortlog -sn HEADshows contributions are dominated by James Ross / J. Kirby Ross plus test and bot identities.- Current docs are extensive but require significant project vocabulary before many tasks become obvious.
Mitigation Plan
- Add CONTRIBUTING fast paths: docs-only PR, fixture-only PR, emitter test PR, CLI bug PR.
- Create small good-first issues tied to one file and one test command.
- Add maintainer-independent release and triage runbooks with exact commands.
- Mark advanced/system-theory docs as design background, not required reading.
- Add public examples from at least one sibling consumer while keeping ownership boundaries explicit.
Acceptance Criteria
- A first-time contributor can identify a safe issue, branch, test command, and PR checklist in under 10 minutes.
- Good-first issues avoid internal vocabulary unless the issue is specifically about docs vocabulary.
- Contributor docs distinguish required workflow from optional architecture background.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
docsDocumentation changesDocumentation changesdocumentationImprovements or additions to documentationImprovements or additions to documentationenhancementNew feature or requestNew feature or requestlegend:DXDeveloper experience workDeveloper experience worklegend:PROCESSMethod/process workMethod/process workstatus: non-blockingThis issue is not a blocker for a release.This issue is not a blocker for a release.triage:requestsUnscheduled valid requests that still need a release scheduling decisionUnscheduled valid requests that still need a release scheduling decisionwork-in-progressMethod issue is actively being workedMethod issue is actively being worked
Activity
flyingrobots commentedon Jul 4, 2026
Opened PR #692 for this slice: #692
Implemented a first-PR contributor path, linked it from CONTRIBUTING and docs topic routing, added scheduled starter issues #690 and #691, and clarified existing starter issue #649.
Validation run:
pnpm exec prettier --write CHANGELOG.md CONTRIBUTING.md docs/topics/README.md docs/topics/docs-orientation.md docs/topics/contributing/first-pr.md docs/truth-manifest.jsoncargo xtask docs-checkpnpm run preflightgit diff --checkflyingrobots commentedon Jul 5, 2026
Closing as completed by PR #692, which added first-contributor fast paths and contributor starter guidance. The stacked work landed on main through PR #685.