From a2d959c7c115f28ea624b937c95f37b8ae796303 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Sun, 10 May 2026 15:24:19 +0200 Subject: [PATCH] docs(planning): F5 best-practice audit recorded, v1.4.21 backlog seeded - STATE.md: F5 ticked complete with the four atomic commits referenced - phase-F5-report.md: scope + per-commit justification + deferral list - v1421-backlog.md: new backlog file for F5 LOW carry-over plus the FX cleanup carry-over (source-comment sweep, bilingual CHANGELOG, CLAUDE.md/AGENTS.md filenames) Co-Authored-By: Claude Opus 4.7 (1M context) --- .planning/STATE.md | 12 +++---- .planning/phase-F5-report.md | 69 ++++++++++++++++++++++++++++++++++++ .planning/v1421-backlog.md | 44 +++++++++++++++++++++++ 3 files changed, 119 insertions(+), 6 deletions(-) create mode 100644 .planning/phase-F5-report.md create mode 100644 .planning/v1421-backlog.md diff --git a/.planning/STATE.md b/.planning/STATE.md index ec06e3019..32936fdbe 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -57,13 +57,13 @@ Combined sweep across HealthLog main repo + healthlog-docs + healthlog-landing ### F5 — Best-practice GitHub repo audit -- [ ] 2 parallel agents survey repo structure -- [ ] Compare to OSS best-practice (README, LICENSE, CONTRIBUTING, - CODE_OF_CONDUCT, SECURITY, .github/ISSUE_TEMPLATE, - PULL_REQUEST_TEMPLATE, badges) -- [ ] Output prioritized list; apply CRITICAL + HIGH inline; defer - rest to v1.4.21 +- [x] CODE_OF_CONDUCT.md (Contributor Covenant 2.1, `e7b6b27`) +- [x] Issue + PR templates (`.github/ISSUE_TEMPLATE/*.yml`, `PULL_REQUEST_TEMPLATE.md`, `072941b`) +- [x] Dependabot expanded to github-actions + docker (`779e5a3`) +- [x] package.json metadata: description, license, homepage, repository, bugs, keywords (`f7977d1`) +- [x] LOW carry-over (README badges, FUNDING.yml, repo-root tidy) deferred to `.planning/v1421-backlog.md` - Detailed report: `.planning/phase-F5-report.md` +- Note: initial sub-agent dispatch hit a content-filter block on the CoC text; refactored to inline execution (download CoC verbatim from contributor-covenant.org). ### F6 — Multi-agent QA on new docs diff --git a/.planning/phase-F5-report.md b/.planning/phase-F5-report.md new file mode 100644 index 000000000..097b2bd43 --- /dev/null +++ b/.planning/phase-F5-report.md @@ -0,0 +1,69 @@ +# Phase F5 — Best-practice GitHub repo audit + +Status: complete · 2026-05-10T15:30+02:00 + +Initial sub-agent dispatch hit a content-filter block on the +Contributor Covenant text. Refactored to inline execution: download +the CoC verbatim from `contributor-covenant.org`, then add the rest +manually as four atomic commits. + +## Pre-existing compliance pass + +| File | State | +|---|---| +| `README.md` | Comprehensive; no edits | +| `LICENSE` | AGPL-3.0; no edits | +| `CONTRIBUTING.md` | Just extended in F2 with branch model | +| `SECURITY.md` | Current; security@bombeck.io contact | +| `.gitignore` | Standard Next.js + Node coverage | +| `.github/dependabot.yml` | npm only — extended below | + +## Inline fixes (CRITICAL + HIGH) + +Four atomic commits on `develop`: + +| Commit | Adds | +|---|---| +| `e7b6b27` | `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1, conduct@bombeck.io contact) + CONTRIBUTING.md link | +| `072941b` | `.github/ISSUE_TEMPLATE/{bug_report,feature_request,config}.yml` + `.github/PULL_REQUEST_TEMPLATE.md` | +| `779e5a3` | `.github/dependabot.yml` extended with `github-actions` + `docker` ecosystems | +| `f7977d1` | `package.json` metadata: description, license, homepage, repository, bugs, keywords | + +### Why each is non-trivial + +- **CoC** is the OSS baseline GitHub badges check for; absence reads as + "unmoderated project" and discourages participation. Verbatim + Contributor Covenant 2.1 from canonical source. +- **Issue templates** as YAML form schemas (not Markdown) so the + GitHub UI renders structured fields, validates required inputs, + and prevents the "user posts unstructured text → maintainer asks + for version → user re-posts" round-trip. Bug template auto-routes + security to SECURITY.md. +- **PR template** explicitly reminds the contributor to target + `develop`, not `main` — pairs with the F1 branch-model rollout. + Checklist mirrors the local CI command. +- **Dependabot** extension covers `.github/workflows/*` action + versions (the npm-only previous config was silently leaving + `actions/checkout@v4` etc. unmonitored) and the `Dockerfile` base + image. +- **package.json** metadata fills fields that npm scrapers, SBOM + tooling, and GitHub package-cards display. + +## Deferred to v1.4.21 + +Captured in `.planning/v1421-backlog.md` under "F5 — Best-practice +repo audit (deferred MED + LOW)". Five items, all LOW: + +- README badges row +- FUNDING.yml (only if the maintainer enables a sponsor profile) +- Repo-root tidy +- `.gitignore` audit (no gaps spotted) +- Discussions enablement verification + +## Post-run state + +- 4 commits on `origin/develop` (post-push) +- `pnpm install` not re-run (no dependency changes) +- Pre-commit hooks green on every commit; no `--no-verify`, no + `--no-gpg-sign` +- No edits to CHANGELOG.md, docs/audit/*, or any source file diff --git a/.planning/v1421-backlog.md b/.planning/v1421-backlog.md new file mode 100644 index 000000000..e1ca66678 --- /dev/null +++ b/.planning/v1421-backlog.md @@ -0,0 +1,44 @@ +# v1.4.21 backlog + +Carry-over from v1.4.20 marathon foundation phases. Pick from this list +when v1.4.21 starts. + +## F5 — Best-practice repo audit (deferred MED + LOW) + +- **README badges** (LOW). Add a small badge row: build status (GitHub + Actions), license (AGPL-3.0), latest GHCR tag, container size, + package-version. Today the README is content-rich but visually + unanchored. Pure cosmetic. +- **FUNDING.yml** (optional). Skipped because no GitHub Sponsors / Ko-fi / + OpenCollective profile is configured. Add when the maintainer enables + one. +- **Repo-root tidy** (LOW). The root currently carries `coverage/`, + `playwright-report/`, `test-results/` directories which are listed in + `.gitignore` but render as empty entries during `ls -la`. No action + needed unless a future audit re-flags. +- **`.gitignore` audit** (LOW). Inherits Next.js + standard Node patterns. + Spot-check did not surface gaps. +- **Discussions enablement** (LOW). The new `.github/ISSUE_TEMPLATE/config.yml` + links to `https://github.com/MBombeck/HealthLog/discussions`; verify + that Discussions is actually enabled on the repository before v1.4.21 + ships, or remove the link. + +## FX (cleanup) carry-over + +- **Source-comment sweep** (LOW). `src/` has 191 `Marc` references in + maintainer-internal source comments. Visible to anyone who clones the + repo. Lower priority than user-rendered surfaces; schedule for a + hygiene PR. +- **DE+EN bilingual CHANGELOG entries** (MED). v1.4.15-era entries pair + a German sentence with its English translation by historical design. + English-only normalisation is a larger rewrite — defer. +- **`CLAUDE.md` + `AGENTS.md` filenames** (MED). Visible at repo root. + These document AI-agent conventions; renaming is a structural change + with downstream link impact. Defer until a hygiene PR. + +## v1.4.19 backlog passthrough (from `v1420-backlog.md`) + +The v1.4.19 quality-of-life audit deferred 31 MED + 16 LOW + 4 HIGH + +4 reconcile-HIGH items into `.planning/v1420-backlog.md`. v1.4.20 picks +selectively (the redesign owns its own scope); the rest moves here on +v1.4.21 kickoff. See that file for the full list.