From cc70db3bb42c1bbcad678b3e66845421a8331f03 Mon Sep 17 00:00:00 2001 From: Torgny Bjers Date: Sat, 11 Jul 2026 23:32:53 -0400 Subject: [PATCH] docs: add CONTRIBUTING.md and issue templates, close out Phase 7 & 8 Fork-PR and deploy-button flows were verified manually; secret scanning is provided by GitGuardian rather than a committed gitleaks step. With those items and the new CONTRIBUTING.md/issue templates, Phase 7 and 8 are complete in PROGRESS.md and README's status table. Co-Authored-By: Claude Sonnet 5 --- .github/ISSUE_TEMPLATE/bug_report.yml | 65 +++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 27 ++++++++ CONTRIBUTING.md | 74 ++++++++++++++++++++++ README.md | 12 ++-- docs/PROGRESS.md | 14 ++-- 6 files changed, 184 insertions(+), 13 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..87f8747 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,65 @@ +name: Bug report +description: Something in coverage-tracker isn't working as expected. +labels: ['bug'] +body: + - type: textarea + id: description + attributes: + label: What happened? + description: A clear description of the bug. + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: What did you do, step by step? + placeholder: | + 1. ... + 2. ... + 3. ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + + - type: input + id: worker-version + attributes: + label: Worker version / commit + description: The `version` field in `package.json`, or the commit SHA you deployed. + validations: + required: false + + - type: dropdown + id: cloudflare-plan + attributes: + label: Cloudflare plan + options: + - Free + - Paid (Workers/D1) + - Not sure + validations: + required: false + + - type: textarea + id: logs + attributes: + label: Relevant logs + description: Output from `wrangler tail`, browser console, or CI, if applicable. + render: shell + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..466991f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Installation and setup help + url: https://github.com/CoverageTracker/coverage-tracker/blob/main/docs/INSTALLATION.md + about: Questions about deploying or configuring your own instance should start here, not as a bug report. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..6f28dad --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,27 @@ +name: Feature request +description: Suggest an idea for coverage-tracker. +labels: ['enhancement'] +body: + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: What are you trying to do that coverage-tracker doesn't support today? + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed solution + description: What would you like to happen? + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Any workarounds or other approaches you've thought about. + validations: + required: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f15d2ff --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,74 @@ +# Contributing + +Thanks for considering a contribution to coverage-tracker. This is a small, +self-hostable project — most changes should be small too. + +## Project layout + +This repo has **three independent `package.json`s**, each with its own +dependencies: + +| Directory | What it is | +| ------------------------- | ----------------------------------------------------- | +| `/` (root) | The Cloudflare Worker — Hono API + cron rollup | +| `dashboard/` | SvelteKit 5 dashboard, builds into the Worker | +| `.github/actions/report/` | The reporting GitHub Action (parses coverage reports) | + +Install and work on each independently: + +```bash +npm install # root (Worker) +npm --prefix dashboard install # dashboard +npm --prefix .github/actions/report install +``` + +See the root [README.md](README.md#development) for the full local dev loop +(`wrangler.json`, `.dev.vars`, D1 migrations, `npm run dev`). + +## Before opening a PR + +Run these at the root, unless you only touched one sub-project: + +```bash +npm run lint # ESLint (root) +npm run format:check # Prettier (root) +npm run typecheck # tsc --noEmit +npm test # vitest, real D1 bindings via @cloudflare/vitest-pool-workers +``` + +Or check formatting across all three projects at once: + +```bash +npm run format:all:check +``` + +CI (`.github/workflows/ci.yml` and `action-test.yml`) runs the equivalent +checks plus Playwright e2e tests and an Action self-test — a PR won't merge +until those are green. + +## Architecture invariants + +Before touching auth, routing, or the D1 schema, read +[CLAUDE.md](CLAUDE.md) — it documents the non-negotiable invariants for this +project (single Worker serving both the SPA and the API, why `/api/*` must +never sit behind a Cloudflare Access application, the two-table coverage +rollup contract, etc.). PRs that violate one of those invariants will be +asked to change regardless of whether the tests pass. + +## Commit messages + +This repo uses [Conventional Commits](https://www.conventionalcommits.org/): +`feat:`, `fix:`, `chore:`, `docs:`, `ci:`, `test:`, `refactor:`, optionally +scoped (`fix(report): ...`). Look at `git log` for examples. + +## Code review + +[docs/CODEOWNERS](docs/CODEOWNERS) lists who reviews changes to specific +paths. Secret scanning runs automatically via GitGuardian — don't commit +`.dev.vars`, `wrangler.json`, or any real credentials (see the templates: +`.dev.vars.example`, `wrangler.example.jsonc`). + +## License + +By contributing, you agree your contribution is licensed under this repo's +[MIT License](LICENSE). diff --git a/README.md b/README.md index d05a876..80da1ef 100644 --- a/README.md +++ b/README.md @@ -253,12 +253,12 @@ npm run deploy See [docs/PROGRESS.md](docs/PROGRESS.md) for a full breakdown. Current state: -| Phase | Description | Status | -| ----- | ---------------------------------------------------- | ----------- | -| 1–6 | Core Worker, webhooks, dashboard, reporting Action | Complete | -| — | Convergence refactor (single Worker + static assets) | Complete | -| 7 | "Deploy to Cloudflare" button | In progress | -| 8 | Docs, OSS hygiene, public release | In progress | +| Phase | Description | Status | +| ----- | ---------------------------------------------------- | -------- | +| 1–6 | Core Worker, webhooks, dashboard, reporting Action | Complete | +| — | Convergence refactor (single Worker + static assets) | Complete | +| 7 | "Deploy to Cloudflare" button | Complete | +| 8 | Docs, OSS hygiene, public release | Complete | --- diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index bb05695..d48556b 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -154,7 +154,7 @@ Self-test workflow created. Uses `min-coverage: '20'`; actual coverage is 98.09% - [x] **Push to main** — OIDC token mints, `/ingest` accepts it, 2 metrics ingested (`coverage: 98.09%`, `duplication: 0.00%`) - [x] **Push to feature branch** — Action exits cleanly with "Not on default branch (test/matrix-threshold-and-branch ≠ main) — skipping ingest." info log; job green, no 422, no metric written - [x] **PR from same repo** — baselines fetched, Check Run posted on PR head SHA with summary table; pass (`min-coverage: '20'`) and fail (`min-coverage: '99'`) cases both verified via PR #2 -- [ ] **Fork PR** (if applicable) — OIDC mint fails gracefully (warning, not failure); Check Run post skipped gracefully +- [x] **Fork PR** — verified manually: OIDC mint fails gracefully (warning, not failure); Check Run post skipped gracefully - [x] **jscpd** — auto-installs on fresh runner; `Duplication: 0.00% (no clones detected)` collected; appears in Check Run summary table - [x] **Threshold breach** — `min-coverage: '99'` with coverage at 98.09%; action fails with "One or more coverage thresholds were not met.", Check Run posted with `conclusion: failure` @@ -218,21 +218,21 @@ reads the file." See `docs/plans/consumer-generated-reports-migration-plan-v3.md --- -## Phase 7 — "Deploy to Cloudflare" button 🔶 In progress +## Phase 7 — "Deploy to Cloudflare" button ✅ Complete - [x] `deploy` npm script runs `wrangler d1 migrations apply DB --remote` before `wrangler deploy` — uses binding name (`DB`) not database name so the deploy flow works when users specify a different database name - [x] `wrangler.json` committed without `database_id` — Cloudflare's deploy flow provisions D1 automatically and fills in the ID - [x] Button added to `README.md` -- [ ] Validate end-to-end via the deploy button flow (fork the repo, click button, confirm D1 is provisioned and migrations apply) +- [x] Validated end-to-end via the deploy button flow (fork the repo, click button, confirmed D1 provisioned and migrations applied) --- -## Phase 8 — Docs, OSS hygiene, public release 🔶 In progress +## Phase 8 — Docs, OSS hygiene, public release ✅ Complete - [x] `docs/INSTALLATION.md` — full setup guide, updated for converged architecture - [x] Repository public at `github.com/CoverageTracker/coverage-tracker` - [x] `wrangler.example.jsonc` and `.dev.vars.example` committed as templates (updated for convergence) - [x] `README.md` — root-level project overview, quick-start, badge examples (updated for convergence) -- [ ] `CONTRIBUTING.md` -- [ ] GitHub issue templates -- [ ] Pre-commit secret scan (gitleaks) in CI (A9) +- [x] `CONTRIBUTING.md` +- [x] GitHub issue templates +- [x] Secret scanning provided by GitGuardian, per maintainer (supersedes the gitleaks CI step originally planned for A9)