Skip to content

docs: close contributor onboarding gaps and correct the v0.4.x release state#135

Merged
sepehr-safari merged 3 commits into
mainfrom
docs/contributing-onboarding-gaps
Jul 26, 2026
Merged

docs: close contributor onboarding gaps and correct the v0.4.x release state#135
sepehr-safari merged 3 commits into
mainfrom
docs/contributing-onboarding-gaps

Conversation

@sepehr-safari

@sepehr-safari sepehr-safari commented Jul 26, 2026

Copy link
Copy Markdown
Member

Closes #134. Closes #136.

PR #133 was the first external contribution to a good-first-issue. It failed
CI and needed four review items, and three of those four came from gaps in this
guide rather than from anything the contributor did. This closes them.

Changes

pnpm format:check is now documented. It was enforced by CI and named
nowhere in the guide, so following the guide exactly could still fail CI. Both
command lists now match the CI job step for step, with a note that CI stops at
the first failure and that pnpm format applies the fixes.

Hard-coded counts are out of the architecture table. The detection entry
claimed 15 rules; there have been 16 since REPEATED_BOOT_NOTIFICATION landed
in #114. That table is a map of where code lives, not a specification, and its
counts have drifted twice now. The READMEs remain the place that states them,
and the test suite already fails when those drift.

"Adding a Scenario" names all four files that carry the count, and flags
that only two of them fail the suite when missed, which is what makes the other
two easy to skip. Step 4 now says ocpp-debugkit ci covers neither formatting
nor lint nor types.

Station IDs are documented as unique, with a pointer to check
__scenarios__/ for the next free number.

Good-first-issues get a claim policy: one open claim at a time. The previous
wording invited contributors to claim as many as they liked, and one claimed
four within three seconds.

Notes

No changeset. CONTRIBUTING.md is not in the package files list, so nothing
here ships to npm.

CURRENT_STATE.md carries the usual entry, since it is updated inside every PR
before merge.

Also in here: CURRENT_STATE release state (#136)

Folded in rather than branched separately, because it edits regions of
CURRENT_STATE.md adjacent to the entry above and two branches would have
collided.

Current Version reported 0.4.1 with a 0.4.2 patch in progress. 0.4.2 is
published and holds the latest dist-tag, the v0.4.2 tag and GitHub release
exist, and both bugs it tracked (#127, #128) are closed. The active milestone now
reads v0.5.0 with v0.4.x complete, What's Done gains the v0.4.x release record it
never had, and What's Next drops the request to cut v0.4.0, which shipped on
2026-07-17.

The scenario count in this table would otherwise have needed a bump when #133
merges. Removing the count instead drops that coupling.

Verification

pnpm format:check and pnpm lint both pass. Documentation only, no source or
test files touched.

Document `pnpm format:check` in both local verification lists and order them
to match the CI job. CI enforces the format check but the guide never named
it, so a contributor could follow the guide exactly and still fail CI on the
first step after lint.

Drop the hard-coded counts from the architecture table. The detection entry
said 15 rules and has been 16 since REPEATED_BOOT_NOTIFICATION landed. Counts
in that table have now drifted twice, so the READMEs stay authoritative and
the test suite keeps asserting them.

Add both READMEs to the "Adding a Scenario" checklist, note that
`ocpp-debugkit ci` covers neither formatting nor lint nor types, and state
that each scenario takes its own station ID.

Document a one-open-claim-at-a-time policy for good-first-issues.

Closes #134
@sepehr-safari sepehr-safari added type:docs Documentation improvements package:repo Repository-level changes labels Jul 26, 2026
CURRENT_STATE.md is updated inside every PR before merge. Log the first
external good-first-issue contribution and the guide fixes it surfaced.
Current Version reported 0.4.1 with a 0.4.2 patch in progress. 0.4.2 is
published and holds the latest dist-tag, and both bugs it tracked (#127,
#128) are closed.

Restate the active milestone as v0.5.0 with v0.4.x complete, add the
missing v0.4.x release record to What's Done, and drop the stale request
to cut v0.4.0 from What's Next.

Closes #136
@sepehr-safari sepehr-safari changed the title docs: close contributor onboarding gaps in CONTRIBUTING docs: close contributor onboarding gaps and correct the v0.4.x release state Jul 26, 2026
@sepehr-safari
sepehr-safari merged commit 7601a4e into main Jul 26, 2026
2 checks passed
@sepehr-safari
sepehr-safari deleted the docs/contributing-onboarding-gaps branch July 26, 2026 14:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

package:repo Repository-level changes type:docs Documentation improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: CURRENT_STATE still reports 0.4.2 as in progress after it shipped docs: close the contributor onboarding gaps surfaced by PR #133

1 participant