Skip to content

docs: close the contributor onboarding gaps surfaced by PR #133 #134

Description

@sepehr-safari

PR #133, the first external contribution to a good-first-issue, failed CI and
needed four review items. Three of those four trace back to gaps in this repo's
own contributor docs rather than to anything the contributor did.

What went wrong

  1. pnpm format:check is enforced by CI but not documented. CONTRIBUTING.md
    lists pnpm lint, pnpm typecheck, pnpm test, pnpm build under
    "4. Verify Locally", and pnpm lint, pnpm test, pnpm build under
    "Local Setup". CI runs the format check immediately after lint, so a
    contributor can follow the guide exactly and still fail CI. That is what
    happened on feat(scenarios): add firmware update success scenario #133: the run stopped at Format check, and typecheck, build and
    the test suite never executed.

  2. The architecture table carries hard-coded counts that drift.
    CONTRIBUTING.md says detectFailures() has 15 failure rules. There are 16
    since REPEATED_BOOT_NOTIFICATION landed in PR feat(core): detect repeated boot notifications #114. The same table
    hard-codes a scenario count. The READMEs had the identical problem in docs: correct stale detection rule and scenario counts in READMEs #118.

  3. "Adding a Scenario" lists an incomplete set of files. It names
    packages/toolkit/src/scenarios/index.test.ts and
    tests/external-fixture/test.mjs for the count update, and omits README.md
    and packages/toolkit/README.md, which both state the scenario count.

  4. The scenario guidelines do not say station IDs are unique. They give the
    CS-SYNTHETIC-NNN shape and stop there. feat(scenarios): add firmware update success scenario #133 reused CS-SYNTHETIC-012, which
    meter-anomaly.ts already holds.

  5. The good-first-issue claim instructions invite unlimited claims. The
    "How to claim" block asks contributors to comment and says it will be
    assigned, with no limit stated. One contributor claimed Add a new scenario: firmware-update-success #104, Improve test coverage for the summarizer module #106, Add --verbose flag to inspect command #107 and
    Add a new scenario: meter-value-zero #108 within three seconds.

Proposed fix

  • Add pnpm format:check to both command lists, ordered to match the CI job so
    the two stay reproducible against each other.
  • Drop the hard-coded counts from the architecture table. It is a map of where
    code lives, not a specification, and the counts have now drifted twice. The
    authoritative counts stay in the READMEs, where the test suite already asserts
    them.
  • Add both READMEs to the "Adding a Scenario" checklist.
  • State in the scenario guidelines that each scenario takes its own
    CS-SYNTHETIC-NNN.
  • Document a one-open-claim-at-a-time policy in the good-first-issue section.

Scope is CONTRIBUTING.md only. No changeset is needed: the file is not in the
package files list, so it does not ship to npm.

Out of scope

The "How to claim" text in the bodies of the open good-first-issues needs the
same rewording. That is an edit to live issues rather than to the repo, so it is
tracked separately.

Metadata

Metadata

Assignees

No one assigned

    Labels

    package:repoRepository-level changespriority:mediumShould be done in current milestonetype:docsDocumentation improvements

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions