From 4edd7a9aa8c0e39b84f76eb51751fe0cf3c5a267 Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Sun, 26 Jul 2026 16:41:36 +0300 Subject: [PATCH 1/3] docs: close contributor onboarding gaps in CONTRIBUTING 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 --- CONTRIBUTING.md | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3176bdb..72b0042 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,10 +21,12 @@ cd toolkit # Install dependencies pnpm install -# Verify everything works +# Verify everything works (same checks CI runs, in the same order) pnpm lint -pnpm test +pnpm format:check +pnpm typecheck pnpm build +pnpm test ``` ## Monorepo Structure @@ -80,12 +82,12 @@ compose these functions to provide the full analysis pipeline. | Parser | `src/core/parser.ts` | `parseTrace()` — JSON, JSONL, bare array | | Normalizer | `src/core/normalizer.ts` | Event normalization (timestamps, directions) | | Timeline | `src/core/timeline.ts` | `buildSessionTimeline()` — session correlation | -| Detection | `src/core/detection.ts` | `detectFailures()` — 15 failure rules | +| Detection | `src/core/detection.ts` | `detectFailures()` — failure detection rules | | Diff | `src/core/diff.ts` | `diffTraces()` — compare two traces | | Assertions | `src/core/assertions.ts` | `evaluateScenario()` — scenario assertions | | Summarizer | `src/core/summarizer.ts` | Session summary statistics | | Validator | `src/core/validator.ts` | OCPP 1.6 structural validation | -| Scenarios | `src/scenarios/` | 15 predefined scenarios + registry | +| Scenarios | `src/scenarios/` | Predefined scenarios + registry | | Reporter | `src/reporter/` | Markdown + HTML report generators | | Replay | `src/replay/` | Deterministic replay engine | | React | `src/react/` | Reusable UI components | @@ -120,11 +122,17 @@ git checkout -b feat/- ```bash pnpm lint +pnpm format:check pnpm typecheck -pnpm test pnpm build +pnpm test ``` +These are the checks CI runs, in the same order, so a green run here means a +green run there. CI stops at the first failure, which means a formatting problem +masks every result after it. `pnpm format:check` only reports; run `pnpm format` +to apply the fixes. + ### 5. Add a Changeset If your PR changes publishable package behavior, add a changeset: @@ -217,17 +225,26 @@ trace with expected failure outcomes and optional assertions. 2. Import and register it in `packages/toolkit/src/scenarios/index.ts`. -3. Update the scenario count in: +3. Update the scenario count in every place that states it: - `packages/toolkit/src/scenarios/index.test.ts` - `tests/external-fixture/test.mjs` + - `README.md` + - `packages/toolkit/README.md` + + The first two fail the test suite when they drift. The two READMEs do not, so + they are easy to miss. -4. Run `ocpp-debugkit ci` to verify all scenarios pass. +4. Run `ocpp-debugkit ci` to verify all scenarios pass, then run the full local + check from [Verify Locally](#4-verify-locally). `ocpp-debugkit ci` does not + cover formatting, lint, or types. ### Guidelines - All data must be **synthetic** — no real station IDs, transaction IDs, idTags, or personal data. - Use `SYNTHETIC-TAG-NNN` for idTags, `CS-SYNTHETIC-NNN` for station IDs. +- Each scenario takes its own station ID. Check the existing files in + `__scenarios__/` for the next free number rather than reusing one. - `expectedFailures` must align with detection rules available in the current version. - Test your scenario with `ocpp-debugkit scenario run my-scenario`. @@ -278,6 +295,16 @@ new contributors. They should: If you're a new contributor, look for issues with the `good-first-issue` label on the [issues page](https://github.com/ocpp-debugkit/toolkit/issues). +### Claiming One + +Comment on the issue saying you would like to work on it and it will be assigned +to you. + +Please hold one open claim at a time. Once your pull request for it is merged, +say which issue you want next and it will be assigned. This keeps issues from +sitting claimed while another is still in review, so other newcomers can see what +is genuinely free. + ## Security Guidelines OCPP DebugKit processes untrusted input (trace files, pasted content). When From d0f432e3c633d903b071b9ea888144e76439ad16 Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Sun, 26 Jul 2026 16:44:29 +0300 Subject: [PATCH 2/3] docs: record the contributor onboarding fixes in CURRENT_STATE 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_STATE.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md index 3f951b0..7c92d54 100644 --- a/CURRENT_STATE.md +++ b/CURRENT_STATE.md @@ -272,6 +272,19 @@ EVSE model these fixes introduce is required across detection. (vendored) in CI; round-trip tests prove export-then-reparse preserves the consumer view and the events +### Contributor Onboarding Fixes (Issue #134) + +- ✅ First external contribution to a `good-first-issue` arrived (#133, + firmware-update-success scenario for #104). Second external contributor after + #114. +- ✅ `CONTRIBUTING.md` now documents `pnpm format:check`, which CI enforced and + the guide never named, with both command lists ordered to match the CI job +- ✅ Hard-coded rule and scenario counts dropped from the architecture table + after drifting twice; the READMEs stay authoritative and the suite asserts them +- ✅ "Adding a Scenario" names all four files carrying the count, and station + IDs are documented as unique per scenario +- ✅ Good-first-issues carry a one-open-claim-at-a-time policy + ## What's Next 1. **v0.4.0 release** - both interop halves (#121, #122) are in; cut and From 2023aaa926bc4e4fe28ccccd93fa79092cdd141b Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Sun, 26 Jul 2026 17:22:52 +0300 Subject: [PATCH 3/3] docs: correct the v0.4.x release state in CURRENT_STATE 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 --- CURRENT_STATE.md | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md index 7c92d54..5f70138 100644 --- a/CURRENT_STATE.md +++ b/CURRENT_STATE.md @@ -4,21 +4,21 @@ ## Current Version -`0.4.1`, METER_VALUE_ANOMALY fix (published 2026-07-22). A `0.4.2` patch is in -progress (STATUS_TRANSITION_VIOLATION per-connector fix, #128). +`0.4.2`, STATUS_TRANSITION_VIOLATION per-connector fix (published 2026-07-22). +The v0.4.x line is complete. ## Active Milestone -**v0.4.x - detection correctness patches, then v0.5.0 (OCPP 2.0.1)** +**v0.5.0 (OCPP 2.0.1), after a complete v0.4.x** v0.4.0 shipped the Open OCPP Trace interop: the toolkit reads and writes the shared v1.1 interchange format (input adapter #121, exporter + `convert` CLI -#122), checked against the specification's conformance fixtures. Two -false-positive bugs shiv3 found from the simulator integration are being -fixed: `METER_VALUE_ANOMALY` measurand/connector flattening (#127, shipped in -0.4.1) and `STATUS_TRANSITION_VIOLATION` global status tracking (#128, in -0.4.2). Next milestone is **v0.5.0 (OCPP 2.0.1)**, where the per-connector / -EVSE model these fixes introduce is required across detection. +#122), checked against the specification's conformance fixtures. Both +false-positive bugs shiv3 found from the simulator integration are fixed and +released: `METER_VALUE_ANOMALY` measurand/connector flattening (#127, in 0.4.1) +and `STATUS_TRANSITION_VIOLATION` global status tracking (#128, in 0.4.2). Next +milestone is **v0.5.0 (OCPP 2.0.1)**, where the per-connector / EVSE model +these fixes introduce is required across detection. ## What's Done @@ -272,6 +272,16 @@ EVSE model these fixes introduce is required across detection. (vendored) in CI; round-trip tests prove export-then-reparse preserves the consumer view and the events +### v0.4.x Releases + +- ✅ `@ocpp-debugkit/toolkit@0.4.0` published 2026-07-17, Open OCPP Trace + interop (#121, #122) +- ✅ `@ocpp-debugkit/toolkit@0.4.1` published 2026-07-22, `METER_VALUE_ANOMALY` + scoped to cumulative energy registers per connector (Issue #127, PR #129) +- ✅ `@ocpp-debugkit/toolkit@0.4.2` published 2026-07-22, + `STATUS_TRANSITION_VIOLATION` tracked per connector (Issue #128, PR #131) +- ✅ Git tags + GitHub releases `v0.4.0`, `v0.4.1`, `v0.4.2` created + ### Contributor Onboarding Fixes (Issue #134) - ✅ First external contribution to a `good-first-issue` arrived (#133, @@ -287,13 +297,11 @@ EVSE model these fixes introduce is required across detection. ## What's Next -1. **v0.4.0 release** - both interop halves (#121, #122) are in; cut and - publish `v0.4.0` -2. **v0.5.0 - OCPP 2.0.1 Support** - extend the engine beyond 1.6J: message +1. **v0.5.0 - OCPP 2.0.1 Support** - extend the engine beyond 1.6J: message set, device model, scenarios, and detection -3. **v1.0.0 - Stable FOSS Ecosystem** - API stabilization, 20+ scenarios, docs +2. **v1.0.0 - Stable FOSS Ecosystem** - API stabilization, 20+ scenarios, docs overhaul, contributor onboarding -4. **Future** - active scenario runner (live endpoint testing), playground, +3. **Future** - active scenario runner (live endpoint testing), playground, YAML trace format support ## Known Blockers / Decisions Pending