From 0300d3760ca7041f0f75910fb7ba27402a235d3c Mon Sep 17 00:00:00 2001 From: Adam Patch Date: Mon, 12 Jan 2026 17:40:36 -0500 Subject: [PATCH 1/2] docs(process): add Branching & CI policy; link from README and E2E docs; reinforce single-branch rule in cycles; add PR template --- .github/pull_request_template.md | 66 ++++++++++++-------------------- README.md | 3 ++ docs/branching-and-ci.md | 38 ++++++++++++++++++ docs/e2e-testing.md | 3 ++ 4 files changed, 68 insertions(+), 42 deletions(-) create mode 100644 docs/branching-and-ci.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1c065d4..3667ec4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,42 +1,24 @@ -Title: E2E foundation, contracts, and CI - -Summary -- Implements Playwright E2E scaffold with smoke + core flow specs (browse, scan) -- Adds minimal API contracts for /api/scan, /api/scans//status, /api/directories -- Aligns Dev CLI timestamps to timezone-aware ISO8601 -- Adds stable data-testid hooks to UI templates -- Wires CI for pytest and strict E2E smoke -- Updates docs/testing.md with quickstarts and CI notes - -Related -- Story: story:e2e-testing -- Phase: 02–03 -- Task(s): - - task:e2e:02-playwright-scaffold (Done) - - task:e2e:03-core-flows (partially addressed by initial specs; remaining flows in next branch) - -Local verification -- Python tests: python -m pytest -q → green -- Playwright E2E: npm install && npx playwright install --with-deps && npm run e2e → green - -CI -- GitHub Actions workflow runs: - - Python tests (3.11) - - E2E smoke (Node 18) — strict, SCIDK_PROVIDERS=local_fs - -How to run locally -- API contracts: python -m pytest tests/contracts/test_api_contracts.py -q -- E2E: npm run e2e (uses e2e/global-setup.ts to boot the Flask server) - -Risk assessment -- Low risk. Mostly additive tests/config/docs. UI changes limited to data-testid attributes. - -Merge checklist -- [x] pytest green locally -- [x] E2E green locally -- [x] CI expected to pass (strict E2E) -- [x] task:e2e:02-playwright-scaffold marked Done with completed_at -- [ ] Reviewer sanity pass on docs/testing.md and CI workflow - -Post-merge (follow-up branch) -- Expand Phase 03 core flows E2E and refine contracts as needed. +# PR Title + +## Summary +- Short description of the change and why. + +## Linked Work +- Story/Phase: +- Task: + +## Checklist +- [ ] Single active branch: This PR represents my current active branch (exceptions justified below). +- [ ] CI green: Unit tests and smoke checks pass (or expected failures explained). +- [ ] Scope focused: PR covers a single topic and is sized for quick review. +- [ ] Docs updated: README/docs touched if behavior/workflow changed. +- [ ] Tests: Added/updated tests or rationale why not needed. +- [ ] Merge strategy: Prefer rebase onto main; no local merges from other feature branches. + +## Demo Steps (if UI/API visible) +1. +2. +3. + +## Exceptions / Notes +- If working on multiple branches concurrently, document why and link related PRs. diff --git a/README.md b/README.md index c91e606..11fbdc3 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,9 @@ Note: The scanner prefers NCDU for fast filesystem enumeration when available. I - Editable install error (Multiple top-level packages discovered): We ship setuptools config to include only the scidk package. If you previously had this error, pull latest and try again: `pip install -e .`. - Shell errors when initializing env: Use the script matching your shell (`init_env.sh` for bash/zsh, `init_env.fish` for fish). Avoid running `sh scripts/init_env.sh`; instead, source it. +## Branching & CI Policy +To keep CI reliable and PRs easy to review, we follow a simple workflow: one active feature branch per contributor, open small PRs early, and let CI be the gate before merge. See docs/branching-and-ci.md for details and a PR checklist. + ## End-to-End (E2E) tests These tests run in a real browser using Playwright and pytest. The test suite automatically starts the Flask app on port 5001 with safe defaults and no external Neo4j connection. diff --git a/docs/branching-and-ci.md b/docs/branching-and-ci.md new file mode 100644 index 0000000..9ab7fe1 --- /dev/null +++ b/docs/branching-and-ci.md @@ -0,0 +1,38 @@ +# Branching and CI Policy + +Goal: Keep the development flow simple and reliable by working on one active branch at a time and relying on CI to validate changes before merge. + +## Principles +- One active feature branch at a time per contributor. +- Open a Pull Request early and keep it small and focused. +- Let CI be the gate: do not merge locally; wait for required checks to pass. +- Prefer incremental PRs (fast review, fast CI) over large multi‑day PRs. +- If you must work on a second branch, document the reason in the PR description and link to the primary branch/PR. + +## Recommended Flow +1) Create a branch from the default base (main): + - `git switch -c chore/` +2) Push and open a PR as soon as there is a coherent change: + - `git push -u origin HEAD` +3) Keep commits small; push frequently. Let CI run. +4) If CI fails, fix forward on the same branch; avoid force‑push unless rebasing noise. +5) Rebase/update with main when green to reduce drift: + - `git fetch origin && git rebase origin/main` +6) Merge via the PR when required checks pass. + +## PR Checklist +- [ ] The PR covers a single topic; scope is clear in the title/description. +- [ ] Linked story/task and acceptance criteria listed. +- [ ] Tests added/updated; CI is green or expected failures are explained. +- [ ] Docs updated (README or docs/*) if behavior or workflow changed. +- [ ] Justification added if working on multiple branches concurrently. + +## CI Expectations +- Unit tests and smoke checks run on every PR. +- E2E smoke (where applicable) runs within a few minutes (<5s/spec target). +- Required checks must be green before merge. + +## Tips +- Use `python -m dev.cli ready-queue` to confirm current priorities. +- Avoid local merges between feature branches; rebase onto main instead. +- If a PR is taking too long, split it into smaller, independently shippable parts. diff --git a/docs/e2e-testing.md b/docs/e2e-testing.md index 1272050..fc7824e 100644 --- a/docs/e2e-testing.md +++ b/docs/e2e-testing.md @@ -44,3 +44,6 @@ Notes: - If running headless in CI, confirm browsers are installed (`playwright install`). - If optional deps (openpyxl/pyarrow) are not installed, related export tests will be skipped or should target CSV-only paths. - Check server logs for endpoint errors during tests (`/api/interpreters*`, `/api/scans//interpret`). + +## Process note +- We keep one active branch per contributor and rely on CI as the gate. See docs/branching-and-ci.md for details and a short PR checklist. From 099ea6c1742bf23d575e82c40de54d43b64a7ae2 Mon Sep 17 00:00:00 2001 From: Adam Patch Date: Mon, 12 Jan 2026 21:11:42 -0500 Subject: [PATCH 2/2] chore: finalize E2E/Neo4j planning and dev.cli helpers --- docs/e2e-testing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/e2e-testing.md b/docs/e2e-testing.md index fc7824e..74051b6 100644 --- a/docs/e2e-testing.md +++ b/docs/e2e-testing.md @@ -32,6 +32,8 @@ Notes: - Show prioritized Ready Queue: `python -m dev.cli ready-queue` - Validate a task file: `python -m dev.cli validate task:e2e:01-smoke-baseline` - Start working on the top task: `python -m dev.cli start` +- Branch hygiene (non-blocking): `python -m dev.cli branch-guard` (add --json for machine-readable) +- Finish the git (stage, commit, push, print PR link): `python -m dev.cli git-finish -m "chore: update docs"` (add --json for structured output) ## Active Story & Phase - See `dev/cycles.md` for the current Active Story/Phase pointer.