Skip to content

DX: create first-contributor fast paths #682

Closed

Description

@flyingrobots

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 HEAD shows 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.

Activity

  1. added
    legend:DXDeveloper experience work
    triage:requestsUnscheduled valid requests that still need a release scheduling decision
    on Jul 4, 2026
  2. added
    docsDocumentation changes
    documentationImprovements or additions to documentation
    enhancementNew feature or request
    status: non-blockingThis issue is not a blocker for a release.
    v0.3.0Scheduled work for the v0.3.0 release.
    on Jul 4, 2026
  3. added
    work-in-progressMethod issue is actively being worked
    and removed
    v0.3.0Scheduled work for the v0.3.0 release.
    on Jul 4, 2026
  4. flyingrobots commented on Jul 4, 2026

    @flyingrobots
    OwnerAuthor

    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.json
    • cargo xtask docs-check
    • pnpm run preflight
    • git diff --check
    • pre-push Rust product preflight
  5. flyingrobots commented on Jul 5, 2026

    @flyingrobots
    OwnerAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation changesdocumentationImprovements or additions to documentationenhancementNew feature or requestlegend:DXDeveloper experience worklegend:PROCESSMethod/process workstatus: non-blockingThis issue is not a blocker for a release.triage:requestsUnscheduled valid requests that still need a release scheduling decisionwork-in-progressMethod issue is actively being worked

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions