Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions .claude/commands/docs_sync_check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
description: Verify user-facing strings, README, ABOUT and the CHANGELOG match the current app
---

# /docs_sync_check

Cross-check the app's user-facing surface against the docs. Catches drift introduced when a button or tab is renamed in code but the doc still describes the old name, when a device template is renamed but README still lists the old name, or when a feature ships without a docs update. `README.md` and `ABOUT.md` are both rendered inside the app (About tab), so stale text ships to users.

## Severities

- **Critical** — `README.md` or `ABOUT.md` fails to render in-app (markdown the renderer chokes on, or a missing bundled file after a rename).
- **Major** — a workflow step in `README.md` (Quick Start, Common Tasks, Reference) no longer matches the code, or a user-facing control is described under a name that no longer exists.
- **Minor** — a feature or device mentioned in `ABOUT.md` or README's feature/device lists has been removed or renamed but isn't workflow-critical.

## Inputs

- `src/gui/*.py` — window title, tab names, button/menu labels, dialog text, status messages.
- `visual-templates/template_registry.json` — template display names (README lists supported devices).
- `README.md` — Quick Start, Common Tasks, Reference, Troubleshooting.
- `ABOUT.md` — feature summary, acknowledgements.
- `docs/CHANGELOG.md` — `[Unreleased]` must describe every user-visible change on the branch.

## Checks

1. **Bundled docs still load** *(Critical)*: `ABOUT.md` and `README.md` are read via `get_resource_path`; confirm both are in `scripts/build/build_exe.py`'s `--add-data` list and parse as markdown.
2. **String drift** *(Major)*: pull every user-facing literal from `src/gui/` (tab names, button text, dialog titles) and check whether README/ABOUT refer to any of them by a name no longer in the code. Flag `doc:line → code:line` with the suspected new wording.
3. **Workflow currency** *(Major)*: README's Common Tasks cover loading a profile, editing labels, remapping a binding, Device View, Config tab device mapping, exports. If the branch diff touched any of those flows, surface the matching README section for review.
4. **Device list parity** *(Minor, escalate to Major if a how-to names the device)*: every non-deprecated template name in `template_registry.json` should appear where README lists supported devices, and vice versa.
5. **CHANGELOG parity** *(Major)*: compare `git log <base>..HEAD --oneline` with `[Unreleased]`; every user-visible change needs an entry.

## Output

Group findings by severity, one per line: `doc-file:line → code-file:line — short description`.

End with a one-line **verdict**: **Clean**, **Minor issues**, or **Needs attention** (any Critical or Major).

After the verdict, **CHECKPOINT — pause and ask whether to draft doc updates for the Critical/Major findings, or move on.** Do not edit docs without confirmation — surface, don't auto-correct.
117 changes: 89 additions & 28 deletions .claude/commands/pre_release.md
Original file line number Diff line number Diff line change
@@ -1,62 +1,123 @@
---
description: Pre-release gate before merging release/X.Y.Z to main — tests, docs/CHANGELOG currency, security review, tester installer build on the release PR, then issue close-on-verify
description: Pre-release sanity check before merging release/X.Y.Z to main — test coverage, docs sync, standards, security review, contributor + tester acknowledgement audit, tester installer build on the release PR, then issue close-on-verify
---

# /pre_release

Run before merging the active `release/X.Y.Z` integration branch to `main`. This is the final gate: it confirms the tests pass, the CHANGELOG and user docs describe what this release changed, the code is reviewed for security, testers have an installer to verify against, and every issue fixed this cycle is closed (tester-verified) or explicitly held.
Run before merging the active `release/X.Y.Z` integration branch to `main`. This is the final gate before the release ships — it confirms code quality, doc currency, test coverage, that every code contributor and tester is acknowledged in `ABOUT.md`, that testers have an installer to verify against, and that every issue fixed this cycle is closed (tester-verified) or explicitly held.

Work through every step in order. After each step, stop at the **CHECKPOINT** and wait for the user.
Mirrors smart-citizen's `/pre_release`. Three of its steps do not apply here and are omitted on purpose: the language coverage check (SCPE has no translations), the in-app Test Plan panel refresh (SCPE has no such panel), and the portable build (SCPE has no portable mode).

Work through every step in order. After each step, stop at the **CHECKPOINT** and wait for the user before continuing.

## Preflight

- Current branch must be `release/X.Y.Z`; abort otherwise.
- Working tree clean (`git status --porcelain`); abort otherwise.
- `VERSION.TXT` must equal `X.Y.Z`; surface a mismatch and ask.
- Confirm the current branch is `release/X.Y.Z`. If not, abort and ask the user to switch.
- Confirm the working tree is clean (`git status --porcelain`). If dirty, abort.
- Confirm `VERSION.TXT` matches `X.Y.Z`. If mismatched, surface the discrepancy and ask before proceeding.

**CHECKPOINT — preflight confirms release branch is ready for audit. Proceed?** Wait for the user.

## 1. Test coverage check

Follow `.claude/commands/test_coverage_check.md`. Present findings grouped by severity (Critical / Major / Minor) and end with the verdict line.

**CHECKPOINT — ready for the next check?** Wait for the user.

## 2. Docs sync check

Follow `.claude/commands/docs_sync_check.md`. Present findings grouped by severity and end with the verdict line. This is also where `docs/CHANGELOG.md` `[Unreleased]` is brought up to date with the branch's user-visible changes; draft the missing entries in the file's style (`**Bold summary** — detail (issue #N)`). Doc edits land via a normal PR to the release branch.

**CHECKPOINT — ready for the next check?** Wait for the user.

## 3. Standards spot-check

Follow `.claude/commands/standards_check.md`. Present findings grouped by severity and end with the verdict line.

**CHECKPOINT — ready for the next check?** Wait for the user.

## 4. Security review

Run `/security-review` on `main..HEAD`. Present findings grouped by severity and end with the verdict line.

**CHECKPOINT — preflight passes. Proceed?**
**CHECKPOINT — ready for the contributor audit?** Wait for the user.

## 1. Tests
## 5. Contributor & tester acknowledgement audit

Run `python -m pytest tests/ -q`. Everything must pass; there is no skip list. Report failures with their output.
Verify every code contributor and frequent tester is acknowledged in `ABOUT.md` (rendered in the About tab, so this is what users see).

**CHECKPOINT.**
### 5a. Build the contributor list

## 2. CHANGELOG and docs currency
```bash
git log --format='%aN|%aE' --no-merges | sort -u
gh api "repos/Osiris-DevWorks/sc-profile-editor/contributors" --paginate --jq '.[] | {login: .login, contributions: .contributions}'
```

1. `git log main..HEAD --oneline` — the release's scope (merged PRs and the issues they close).
2. Compare against `docs/CHANGELOG.md` `[Unreleased]`: every user-visible change (new feature, changed flow, fixed bug with a reproducible symptom) needs an entry; internal refactors do not. Draft the missing entries in the file's existing style (`**Bold summary** — detail (issue #N)`).
3. Check `README.md` and `ABOUT.md` for anything the release renamed, added or removed (tabs, buttons, supported devices). Both are rendered in-app, so stale text ships to users.
**Filter out**: the repo owner (`Osiris-DevWorks` / `Osiris DevWorks` / `Amr`), AI co-author trailers (`Claude`, `noreply@anthropic.com`), bot accounts (`*[bot]`), and anonymous commits with no name or GitHub login. Merge entries for one person committing under several name/email combinations; if unsure, surface the duplicates.

**CHECKPOINT — present the proposed CHANGELOG/doc edits and ask before editing.** Land them via a normal PR to the release branch (release branches require PRs).
### 5b. Pull the current acknowledgement set

## 3. Security review
Read `ABOUT.md` → `## Acknowledgements` (the tester list) and any **Contributors** section. If `README.md` carries a matching section, read it too and treat drift between the two as a finding.

Run `/security-review` on `main..HEAD`. Present findings grouped by severity (Critical / Major / Minor) and end with a verdict line.
### 5c. Categorize each missing contributor

**CHECKPOINT.**
For every contributor not acknowledged: commit count (`git log --author='<email>' --no-merges --oneline | wc -l`) and a sample of files touched. **Substantial**: ≥3 commits or non-trivial `src/`, `scripts/`, `tests/` or `visual-templates/` changes. **Drive-by**: 1–2 commits, trivial files only.

## 4. Tester installer on the release PR
### 5d. Tester candidates from issue reporters

```bash
gh issue list --state all --limit 1000 --json number,author --jq '.[].author.login' | sort | uniq -c | sort -rn
```

Flag everyone with **3 or more** reported issues as a candidate tester, then drop the owner, bots, anyone already in the Acknowledgements list, and anyone who is also a code contributor (credited as a contributor, never both). Issues mirrored from Discord name the real reporter in the body; attribute by that name, and list unattributable reports rather than guessing.

### 5e. Report

```
**Missing — substantial contributors** (suggest adding): …
**Missing — drive-by fixers** (consider adding, or skip): …
**Already acknowledged**: N covered.

**Tester candidates** (≥3 reported issues, not code contributors): …
```

Verdict: **Clean** (every substantial contributor acknowledged), **Minor issues** (only drive-bys missing or README/ABOUT drift), **Needs attention** (substantial contributors missing). Tester candidates are advisory and never block a release.

**CHECKPOINT — ask before drafting additions to `ABOUT.md` (and `README.md` if it carries the same list).** Do not edit without confirmation.

## 6. Tester installer build on the release PR

1. Find the release PR: `gh pr list --base main --head release/X.Y.Z --state open --json number,title`.
2. If none exists, open it now with title `Release X.Y.Z` and the CHANGELOG section as the body. **Opening the PR is not merging it.**
3. Add the `build-installer` label: `gh pr edit <N> --add-label build-installer`. `installer-preview.yml` builds `SCProfileEditor-vX.Y.Z-Setup.exe` and comments the download link on the PR; later pushes to the PR rebuild automatically.
3. Add the label: `gh pr edit <N> --add-label build-installer`. `installer-preview.yml` builds `SCProfileEditor-vX.Y.Z-Setup.exe` and comments the download link on the PR; later pushes to the PR rebuild automatically. If the label was already present from an earlier round, remove and re-add it, or dispatch the workflow manually, so a build runs on the current head.
4. Report the run (`gh run list --limit 1`) and the artifact name (`scprofileeditor-installer-{SHA}`, 30-day retention).

**CHECKPOINT — confirm before opening the PR and adding the label; both are visible on GitHub and start CI builds.**
**CHECKPOINT — confirm before opening the PR and adding the label; both are visible on GitHub and start CI builds.** Wait for the user.

## 7. Issue close-on-verify pass

Runs last because verification comes from testers using the step-6 build. On the day the audit runs, most issues will legitimately sit in "awaiting verification"; that is the expected outcome. Re-run this step alone once tester sign-offs come back, before the merge to `main`.

### 7a. Gather the release's issues

Union of: issues labeled `next-release` (`gh issue list --state open --label next-release --json number,title,author`) and every `#NN` referenced in `git log main..HEAD --oneline`.

### 7b. Classify each

## 5. Issue close-on-verify
Look for a confirming comment from the reporter or a tester on the preview build (`gh issue view <N> --json title,state,comments`). Bucket as **Fixed + tester-verified** (close), **Fixed, awaiting verification** (hold; a passing local test is not a tester sign-off), or **Not addressed** (flag for re-label or defer).

Runs last because verification comes from testers using the step-4 build.
### 7c. Report

1. Gather issues: `#NN` references in `git log main..HEAD` plus anything labeled `next-release`.
2. For each, check for a tester confirmation (`gh issue view <N> --json title,state,comments`). Bucket as **Verified — close**, **Awaiting verification — hold**, or **Not addressed — re-label or defer**. A passing local test is not a tester sign-off.
3. Report the three buckets.
```
**Verified — close candidates:** …
**Awaiting verification — hold open:** …
**Not addressed — re-label or defer:** …
```

**CHECKPOINT — ask before closing anything.** On confirmation, close each verified issue with a short thanks naming the version it ships in and the tester who confirmed it. Never close one that is only awaiting verification.
**CHECKPOINT — present the close / hold / flag list and ask before closing anything.** On confirmation, close each verified issue with a short thanks naming the version it ships in and crediting the tester who confirmed it. Never close one that is only awaiting verification.

## Final summary

One-line overall verdict (worst case across steps), the remaining Critical/Major findings, and where testing stands. Re-run step 5 alone once tester sign-offs land.
One-line overall verdict for release readiness (the worst case across the checks), the remaining Critical/Major findings to address before the `release/X.Y.Z` → `main` merge, and any issues still open that were expected to ship. Say plainly where testing stands: the build is out, and anything step 7 left in "awaiting verification" is waiting on testers, not on the audit.

This command does not ship the release. That is `/ship_release`.
39 changes: 39 additions & 0 deletions .claude/commands/standards_check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
description: Lint the current diff against SC Profile Editor's documented standards
---

# /standards_check

Audit the branch diff (`git diff $(git merge-base HEAD <base>)...HEAD`, plus any working-tree changes) against the project's documented standards in `CLAUDE.md` and `docs/DEVELOPMENT.md`. Report findings with file:line references and severity. **Do not auto-fix without confirmation.**

- **Critical** — breaks correctness, the packaged build, or the XML round-trip. Must fix before merge.
- **Major** — wrong but won't immediately break. Should fix before merge.
- **Minor** — stylistic or "consider" notes. Optional.

## Checks

- **Bundled resource lookup** *(Critical)*: any `open(...)`, `Path(...)` or `os.path.join(...)` that reaches a bundled file (`visual-templates/`, `example-profiles/`, `default-bindings/`, `assets/`, `UNBIND_ALL.xml`, `label_overrides.json`, `README.md`, `ABOUT.md`, `VERSION.TXT`) without going through the `_MEIPASS`-aware `get_resource_path()` helper. Works in dev, breaks in the installer.
- **Build data list** *(Critical)*: a new bundled file or folder that is not in `scripts/build/build_exe.py`'s `--add-data` list (and the matching list in `docs/DEVELOPMENT.md`).
- **Bare `src/` imports** *(Critical)*: new modules must import the same way their neighbours do (`from parser.xml_parser import …`, resolved by `--paths src`). A mix of `src.parser` and `parser` imports breaks the frozen build.
- **activationMode on axes** *(Critical)*: any code path that writes `activationMode` for an input `InputValidator.is_analog_axis()` says is analog, or that writes a default mode the user did not pick (the v0.10.2 hat bug: an explicit `press` overrides the game's `hold`). `None` means "game default" and must stay omitted in the XML.
- **Settings access** *(Major)*: direct `QSettings(...)` construction outside `src/utils/settings.py`. Use `AppSettings` so keys and the registry path stay in one place.
- **Label resolution** *(Major)*: display labels must resolve through `src/utils/label_overrides.py` (custom → global → auto-generated). A new code path that formats an action name directly bypasses user overrides.
- **Template registry** *(Major)*: new templates need `device_match_patterns` that match the SC product string case-sensitively, a `product_ids` list where the VID/PID is known, and `field_mapping.json` next to the PDF. Composite devices route through `device_splitter.py`; don't special-case them in the manager.
- **Version source** *(Major)*: any literal version string in code, `installer.iss`, or docs other than `VERSION.TXT`. The window title, installer and release tag all derive from that file.
- **Logging** *(Minor)*: `print()` in `src/` instead of the module `logger`.

## Code duplication / DRY

- **Copy-paste blocks** *(Major)*: 5+ line blocks in the diff that appear verbatim elsewhere. Report both locations.
- **Magic literals** *(Minor)*: SC input prefixes (`js1_`, `kb1_`, `mouse1_`, `gp1_`), the PIDVID GUID suffix, QSettings keys, template ids repeated in 2+ places without a named constant.
- **Near-duplicate functions** *(Minor)*: a new function structurally identical to an existing one, differing only in a literal or a call target.

Calibration: 3+ occurrences → recommend extraction; 2 → "consider"; never propose a single-use helper.

## Output

Group findings by severity, one per line: `file:line — short description — fix hint`.

End with a one-line **verdict**: **Clean**, **Minor issues**, or **Needs attention** (any Critical or Major).

After the verdict, **CHECKPOINT — pause and ask whether to draft fixes for the Critical/Major findings, or move on.** Wait for the answer before doing anything else.
Loading
Loading