Repository navigation
docs: close the contributor onboarding gaps surfaced by PR #133 #134
Description
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
-
pnpm format:checkis enforced by CI but not documented.CONTRIBUTING.md
listspnpm lint,pnpm typecheck,pnpm test,pnpm buildunder
"4. Verify Locally", andpnpm lint,pnpm test,pnpm buildunder
"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. -
The architecture table carries hard-coded counts that drift.
CONTRIBUTING.mdsaysdetectFailures()has 15 failure rules. There are 16
sinceREPEATED_BOOT_NOTIFICATIONlanded 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. -
"Adding a Scenario" lists an incomplete set of files. It names
packages/toolkit/src/scenarios/index.test.tsand
tests/external-fixture/test.mjsfor the count update, and omitsREADME.md
andpackages/toolkit/README.md, which both state the scenario count. -
The scenario guidelines do not say station IDs are unique. They give the
CS-SYNTHETIC-NNNshape and stop there. feat(scenarios): add firmware update success scenario #133 reusedCS-SYNTHETIC-012, which
meter-anomaly.tsalready holds. -
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:checkto 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.
Activity
docs: close contributor onboarding gaps and correct the v0.4.x releas…