diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b74f306..45033c0 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -3,7 +3,7 @@ ## Milestones - ✅ **v1.0 MVP** — Phases 1–6 (shipped 2026-06-10) — see [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROADMAP.md) -- 🚧 **v1.1 Operability & Polish** — Phases 7–14 (planning) — mobile test harness, Gitea CI (runs the harness), faster write-back, in-app admin, per-event reminders, guided setup, real lint gate, desktop e2e +- 🚧 **v1.1 Operability & Polish** — Phases 7–15 (planning) — mobile test harness, Gitea CI (runs the harness), faster write-back, in-app admin, per-event reminders, guided setup, real lint gate, desktop e2e, doc-only CI skip ## Phases @@ -21,7 +21,7 @@ Full phase detail archived in [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROA -### 🚧 v1.1 Operability & Polish (Phases 7–14) +### 🚧 v1.1 Operability & Polish (Phases 7–15) Make FamilySync configurable, administrable, and maintainable for real multi-member use — without hand-editing env files or the database. The new critical path runs **mobile test harness → Gitea CI** (CI consumes the harness specs for UI regression), and the **admin role → reminders / setup wizard** chain (a single `/api/admin` + `/api/setup` route surface carrying the v1.1 DB migration). Faster write-back is a fully independent track. @@ -33,6 +33,7 @@ Make FamilySync configurable, administrable, and maintainable for real multi-mem - [ ] **Phase 12: Initial Setup Wizard** - First-run validated bootstrap of env/VAPID/DB/OIDC + first app password, reusing the admin route surface - [x] **Phase 13: Real Lint Gate (ESLint)** - Wire ESLint flat config (typescript-eslint + React) across both apps so the Phase 8 CI lint slot actually fails on violations instead of no-op'ing (completed 2026-06-12) - [x] **Phase 14: Desktop E2E Coverage** - Add a Desktop Chrome Playwright profile + make the mobile-authored specs desktop-safe so the Phase 8 regression gate validates desktop, not just mobile (completed 2026-06-12) +- [ ] **Phase 15: Doc-Only CI Skip** - Aggregate-gate the slow api/harness CI jobs so doc-only PRs to main merge without running them, without deadlocking branch protection (promoted from backlog 999.17) ## Phase Details @@ -259,6 +260,26 @@ Plans: **UI hint**: no +### Phase 15: Doc-Only CI Skip + +**Goal**: Doc-only PRs to `main` merge without running the slow `harness` (Playwright e2e + dev-stack bring-up, ~5 min) and `api` (MariaDB integration) jobs, while `fast-checks` (Prettier `format:check` covers markdown) still runs — and branch protection never deadlocks on a required check that never reports. +**Mode:** standard +**Depends on**: Phase 8 (the `.gitea/workflows/ci.yml` it modifies) and Phase 13 (the `format:check` step that must keep running on docs). Independent of Phases 9–12. +**Requirements**: TBD (promoted from backlog 999.17) +**Success Criteria** (what must be TRUE): + + 1. A doc-only PR to `main` (only `docs/` or `*.md` changed) skips the `api` and `harness` jobs but still runs `fast-checks`. + 2. A PR touching code runs `fast-checks`, `api`, and `harness` as today; a failure in any blocks the merge. + 3. Branch protection requires `CI / fast-checks` + an always-running `CI / gate` aggregate (passes when each heavy job is `success` OR `skipped`) — the direct `api`/`harness` requirements are dropped so a skipped heavy job never deadlocks the merge. + +**Pitfalls this phase owns**: + + - **Required-check deadlock** — never path-filter a required context directly; a required job that never reports blocks the PR forever. The always-running `gate` job (`if: always()`, passes on `success`/`skipped`) is the only safe gating surface. + - **Gitea skipped-status quirk** — Gitea may not emit a commit-status for a `skipped` job; rely on the always-running `gate`, not on marking `api`/`harness` skipped-but-required. + +**Plans**: TBD +**UI hint**: no + ## Progress | Phase | Milestone | Plans Complete | Status | Completed | @@ -277,6 +298,7 @@ Plans: | 12. Initial Setup Wizard | v1.1 | 0/? | Not started | - | | 13. Real Lint Gate (ESLint) | v1.1 | 3/3 | Complete | 2026-06-12 | | 14. Desktop E2E Coverage | v1.1 | 1/1 | Complete | 2026-06-12 | +| 15. Doc-Only CI Skip | v1.1 | 0/? | Not started | - | ## Backlog @@ -466,29 +488,3 @@ Plans: Plans: - [ ] TBD (promote with /gsd-review-backlog when ready) - -### Phase 999.17: CI — let doc-only PRs skip the slow api + harness jobs (BACKLOG) - -**Goal:** [Captured for future planning] Make doc-only PRs to `main` mergeable without running the slow `harness` (Playwright e2e + dev-stack bring-up, ~5 min) and `api` (MariaDB integration) jobs, while keeping `fast-checks` (which must run on docs — Phase 13's `format:check` is `prettier --check .` and covers markdown; ~1–2 min). - -**The footgun:** branch protection currently requires three contexts — `CI / fast-checks`, `CI / api`, `CI / harness`. The naive fix (`paths-ignore` on the workflow, or path-filtering `harness`) **deadlocks**: on a docs-only PR the required `harness`/`api` contexts never report, so the PR can never merge. A required check that never reports is worse than a slow one. - -**Solution (Option A — aggregate gate):** - -- Add a cheap `changes` detector job: `git diff --name-only base...HEAD`, set `code=true` unless every changed path matches `docs/` or `*.md`. -- Gate the heavy jobs: `api` and `harness` get `needs: changes` + `if: needs.changes.outputs.code == 'true'`. -- Add an always-running `gate` job: `needs: [fast-checks, api, harness]`, `if: always()`, passes when each dependency `result` is `success` OR `skipped`. -- Change Gitea branch protection to require `CI / fast-checks` + `CI / gate` (drop the direct `api`/`harness` requirements). -- Result: docs PR → `api`/`harness` skip, `gate` passes; code PR → all run, `gate` passes only if they succeed. No deadlock because `gate` always reports. - -**Gitea caveat:** historically Gitea may not emit a commit-status for a `skipped` job — the always-running `gate` sidesteps that entirely (don't rely on marking `api`/`harness` themselves as skipped-but-required). - -**Files:** `.gitea/workflows/ci.yml` + Gitea branch-protection settings. -**Context:** Surfaced 2026-06-12 while opening the docs-only PR #9, which had to run the full harness. Tags: ci, gitea, branch-protection, docs, performance. - -**Requirements:** TBD -**Plans:** 0 plans - -Plans: - -- [ ] TBD (promote with /gsd-review-backlog when ready) diff --git a/.planning/phases/999.10-admin-settings-administration-section/.gitkeep b/.planning/phases/15-ci-skip-api-harness-jobs-for-doc-only-prs/.gitkeep similarity index 100% rename from .planning/phases/999.10-admin-settings-administration-section/.gitkeep rename to .planning/phases/15-ci-skip-api-harness-jobs-for-doc-only-prs/.gitkeep diff --git a/.planning/phases/999.11-initial-setup-wizard/.gitkeep b/.planning/phases/999.11-initial-setup-wizard/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/.planning/phases/999.12-assistant-driven-mobile-browser-ui-testing/.gitkeep b/.planning/phases/999.12-assistant-driven-mobile-browser-ui-testing/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/.planning/phases/999.13-reduce-event-write-back-latency-outbox-drain/.gitkeep b/.planning/phases/999.13-reduce-event-write-back-latency-outbox-drain/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/.planning/phases/999.14-gitea-ci-regression-and-docker-publish/.gitkeep b/.planning/phases/999.14-gitea-ci-regression-and-docker-publish/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/.planning/phases/999.15-desktop-e2e-coverage-for-the-pwa-harness/.gitkeep b/.planning/phases/999.15-desktop-e2e-coverage-for-the-pwa-harness/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/.planning/phases/999.17-ci-skip-api-harness-jobs-for-doc-only-prs-path-filter-aggreg/.gitkeep b/.planning/phases/999.17-ci-skip-api-harness-jobs-for-doc-only-prs-path-filter-aggreg/.gitkeep deleted file mode 100644 index e69de29..0000000