From 1698d53d38d671a4d1b6e81204d5ff5b6c3fa04d Mon Sep 17 00:00:00 2001 From: Adam Moussa Date: Fri, 18 Sep 2026 19:19:55 -0400 Subject: [PATCH] chore(repo): add PR template, fix README conventions, drop tracked scratch files The org PR template pre-filled Summary / Validation / Tests / Notes here while PRs in this repository use Summary / Changes and value / Ticket. A repo template now overrides the org one, and the review framework gains the description contract plus a note on the divergence from the org pr-policy workflow, which is not wired in. README: the CI badge tracked the retired dev branch; branches come from main, not dev; the fix/ prefix replaces bug/; staging exists alongside dev; and PRs now merge through the merge queue. Cleanup: four PR description drafts under tmp/ were tracked; they are removed and /tmp/ is ignored. --- .github/PULL_REQUEST_TEMPLATE.md | 22 ++++++++++ .gitignore | 3 ++ README.md | 20 +++++---- REVIEW_AND_PR_FRAMEWORK.md | 16 +++++++ tmp/pr-descriptions/pr2-severity-wizard.md | 43 ------------------- .../pr4-uplift-pending-close-gate.md | 39 ----------------- tmp/pr-descriptions/pr7-add-technician.md | 27 ------------ tmp/pr-descriptions/pr9-comment-mentions.md | 41 ------------------ 8 files changed, 53 insertions(+), 158 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 tmp/pr-descriptions/pr2-severity-wizard.md delete mode 100644 tmp/pr-descriptions/pr4-uplift-pending-close-gate.md delete mode 100644 tmp/pr-descriptions/pr7-add-technician.md delete mode 100644 tmp/pr-descriptions/pr9-comment-mentions.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..15f9114e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ + + +## Summary + + + +## Changes and value + + + +## Ticket + + diff --git a/.gitignore b/.gitignore index 9536adc7..e3a043a2 100644 --- a/.gitignore +++ b/.gitignore @@ -49,3 +49,6 @@ seed-data.sql # python __pycache__/ *.py[cod] + +# local scratch +/tmp/ diff --git a/README.md b/README.md index 7e2acaa2..4d0edbc3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # SHOC Frontend (`shoc-frontend-new`) -[![CI](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/ci.yaml/badge.svg?branch=dev)](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/ci.yaml) +[![CI](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/ci.yaml) [![Deploy](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/deploy-web.yaml/badge.svg)](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/deploy-web.yaml) ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white) ![React](https://img.shields.io/badge/React-087EA4?logo=react&logoColor=white) @@ -13,7 +13,8 @@ the legacy SHOC frontend — new code follows the IrisLoan.Admin conventions documented in [`docs/ARCHITECTURE_PLAN.md`](docs/ARCHITECTURE_PLAN.md). - **GitHub:** `Sea-Haven-Industries/shoc-frontend-new` -- **Hosted at:** (dev environment; the only environment today) +- **Hosted at:** (dev, deployed from `main`) and + (staging, deployed from `vX.Y.Z-staging` tags) - **Backend API:** `https://api.dev.seahaven.com/api` (called directly, cross-origin) — source: `Sea-Haven-Industries/shoc-backend` ## Architecture @@ -122,16 +123,19 @@ commitlint enforces conventional commit messages. Run `npx tsc --noEmit` (or ## Contributing -- Branch from `dev` with a kebab-case description and a prefix matching the - work: `feature/`, `bug/`, `hotfix/`, `chore/`, `docs/`, or `refactor/` +- Branch from `main` with a kebab-case description and a prefix matching the + work: `feature/`, `fix/`, `hotfix/`, `chore/`, `docs/`, or `refactor/` (e.g. `feature/vendor-portal-filters`, `chore/sea-haven-branding`). - Commit messages follow [Conventional Commits](https://www.conventionalcommits.org) — commitlint rejects anything else at commit time. -- Open PRs against `main`. Protected branches need a green CI run and an - approving review from a code owner - (`@Sea-Haven-Industries/internal-dev`); new pushes dismiss stale approvals. - Merged branches are deleted automatically. +- Open PRs against `main`. The PR body uses the three-section layout the + template pre-fills: Summary, Changes and value, Ticket. `main` needs the + `governance` and `Build and test / ci` checks and an approving review from a + code owner (`@Sea-Haven-Industries/internal-dev`); new pushes dismiss stale + approvals. PRs merge through the merge queue, so a branch does not need to + be updated with `main` before it merges. Merged branches are deleted + automatically. - PRs cannot mix `terraform/` with deployable application files (G13). Workflow, docs, and gate-script changes may travel with either side. `deploy-web.yaml` still ignores `terraform/**` so a Terraform-only merge does not sync the bucket. diff --git a/REVIEW_AND_PR_FRAMEWORK.md b/REVIEW_AND_PR_FRAMEWORK.md index 911e8042..fbf5eccf 100644 --- a/REVIEW_AND_PR_FRAMEWORK.md +++ b/REVIEW_AND_PR_FRAMEWORK.md @@ -90,3 +90,19 @@ that includes both `terraform/` and deployable application files (`src/`, `public/`, `pages/`, `config/`, `index.html`, Vite/tsconfig, or `.env*`) fails G13. Workflow, docs, and gate-script changes may travel with either side. + +## 8. PR description contract (minimal) + +- **Summary** — what changed and why, in plain language. +- **Changes and value** — grouped by area, each with the value it delivers. +- **Ticket** — the board key(s) when one applies; "None" otherwise. +- Link any ADR relied upon. + +Avoid boilerplate: no deployment notes, no validation transcripts, no +"residual-risk" theatre, no AI signatures. The validation story lives in the +check run results and the close-out, not in the PR body. + +`.github/PULL_REQUEST_TEMPLATE.md` pre-fills this layout and overrides the org +template, whose Summary / Validation / Tests / Notes headings this repository +does not use. The org `callable-pr-policy` workflow hard-codes those four +headings; it is not wired into this repository, and this layout is the reason. diff --git a/tmp/pr-descriptions/pr2-severity-wizard.md b/tmp/pr-descriptions/pr2-severity-wizard.md deleted file mode 100644 index c11c1978..00000000 --- a/tmp/pr-descriptions/pr2-severity-wizard.md +++ /dev/null @@ -1,43 +0,0 @@ -## Jira - -- [SH-192](https://luby-us.atlassian.net/browse/SH-192) — severity on Emergency/Reactive -- Related: [SH-107](https://luby-us.atlassian.net/browse/SH-107) (WO# provisional SH…), [SH-108](https://luby-us.atlassian.net/browse/SH-108) (POC) - -## QA residual - -- P0 wizard fixed: Type optional (default PM); WO# alphanumeric / SH provisional (not digits-only). -- P1: COL_HELP tooltips, Scheduled-requires-date — follow-up. - -## Summary - -- Add SEV 1–5 domain field on board row/create/patch and Type cell modal for Emergency/Reactive. -- Wizard gates: required WO# (alphanumeric/SH ok), Type optional (defaults PM), severity when E/R, POC name/phone on step 2 with error UX. - -## Scope - -### In - -- `severity` on WorkOrderBoardRowApi / create payload / editable field / table row / wizard draft -- Type cell popover + TypeSeverityModal + SeverityBadge -- Wizard step1/step2 validation + footer attempt-continue errors -- Unit tests for canContinue* and severity patch mapping - -### Out (follow-up PRs) - -- Advanced filter severity facet (PR5) -- Uplift UI, Completed Date column, multi-POC, SH auto-numbering beyond wizard gate - -## API / BE - -- Contract assumed: `severity` on GET board/search row, POST create, and PATCH field `severity` -- Blocked on BE: none for FE wiring; 422 if severity missing for E/R should be handled by BE - -## Test plan - -- [ ] Board: pick Emergency/Reactive → severity modal required; badge shows SEV -- [ ] Wizard: cannot continue step1 without WO#; E/R without severity; step2 without POC -- [ ] `npm run verify` green locally - -## Base - -- Base branch: `dev` diff --git a/tmp/pr-descriptions/pr4-uplift-pending-close-gate.md b/tmp/pr-descriptions/pr4-uplift-pending-close-gate.md deleted file mode 100644 index 13a8b08c..00000000 --- a/tmp/pr-descriptions/pr4-uplift-pending-close-gate.md +++ /dev/null @@ -1,39 +0,0 @@ -# PR4 — Pending uplift close gate (+ SH-114 closability union) - -## Summary - -Blocks marking a work order **Completed** (and future completion-document generation) when closability gaps remain — **SH-114 field gates ∪ pending uplift** (SH-188). - -- Unifies `wo-closability.ts` / `getClosabilityGaps` with hierarchy: **fields → uplift pending → completion document / photos**. -- Field gates: dispatcher, technician, completed date, real WO# (non-SH), service; then PM/Overdue completion doc; Emergency/Reactive ≥1 photo. -- Pending uplift via `hasPendingUplift` or `upliftSummary.pendingCount`. -- Completed tooltip uses design copy when the **only** gap is pending uplift. -- Maps optional `completedDate` on board rows for the Completed Date gate. - -## Jira - -- [SH-188](https://luby-us.atlassian.net/browse/SH-188) — pending uplift close gate -- Related: [SH-114](https://luby-us.atlassian.net/browse/SH-114) — closability field matrix (pulled into this branch so sister merges do not wipe gates) - -## Comp Doc Generate - -`CompDocDialog` is **not** mounted on `dev` yet. This PR exports `canGenerateCompDoc(row)` so the completion-doc slice can block generate/open with the same reason string. No UI wiring in this PR. - -## Out of scope - -- Full uplift CRUD (PR3) -- Advanced filter facets for uplift -- Scheduled-requires-date gate (design P1) -- COL_HELP tooltips (P1) - -## Test plan - -- [ ] Row with all fields ok + `hasPendingUplift: true` — Completed disabled; design tooltip about pending uplift. -- [ ] Row missing dispatcher / completed date — Completed disabled; `Missing: …` tooltip. -- [ ] Row fully closable — Completed selectable. -- [ ] `canGenerateCompDoc` blocked when gaps exist. -- [ ] Board API `completedDate` / `upliftSummary.pendingCount` map through to the gate. - -## Base - -Branch `feature/wo-uplift-pending-close-gate` from local `dev`. Merge **before** or instead of stacking raw SH-114 alone with an uplift-only closability overwrite. diff --git a/tmp/pr-descriptions/pr7-add-technician.md b/tmp/pr-descriptions/pr7-add-technician.md deleted file mode 100644 index 6ee69d9b..00000000 --- a/tmp/pr-descriptions/pr7-add-technician.md +++ /dev/null @@ -1,27 +0,0 @@ -## Jira - -- [SH-193](https://luby-us.atlassian.net/browse/SH-193) - -## QA residual - -- P0 done: technician is staged as a **local draft** until the vendor dialog is saved / wizard submitted — Cancel does not orphan a vendor row. - -## Summary - -- Adds **+ Add technician** to the WO board vendor dialog when a company context is known (from the row or the current selection). -- Stages a draft technician locally (`draft:` id) without calling `POST vendors` until the dialog save commits the selection. -- On save, create runs via the existing **`POST vendors`** REST endpoint (`vendorsApi.create` / `useCreateVendor`) using the company profile + new `contactName`. - -## Backend - -Uses the established vendor create API (`API_PATHS.rest.vendors` → `POST /vendors`). Each vendor record represents one technician; linking to an existing company is done by sending the same `companyName` (and optional `companyId` when available). **No new endpoint**. - -## Test plan - -- [ ] Open vendor dialog → **+ Add technician** → fill name → Cancel dialog → no vendor create API call. -- [ ] Add technician → Save dialog → `POST /vendors` once; row shows new tech. -- [ ] `npm run verify` - -## Out of scope - -- Multi-POC, multi-tech arrays on WO, vendors directory redesign. diff --git a/tmp/pr-descriptions/pr9-comment-mentions.md b/tmp/pr-descriptions/pr9-comment-mentions.md deleted file mode 100644 index a3c588db..00000000 --- a/tmp/pr-descriptions/pr9-comment-mentions.md +++ /dev/null @@ -1,41 +0,0 @@ -# PR9 — Work order comment @mentions - -## Jira - -- [SH-217](https://luby-us.atlassian.net/browse/SH-217) — FE @mention autocomplete / chips -- Related BE: [SH-75](https://luby-us.atlassian.net/browse/SH-75) - -## QA residual - -- Parcial / Blocked-BE for notification + structured `mentions[]` confirm; token chip polish = P1. - -## Summary - -- Adds `@` autocomplete to the internal comments composer on work order detail (`/workorders/:id`). -- Encodes selected users as `@[userId:Display Name]` tokens in comment text so mentions stay readable when the backend ignores the optional payload field. -- Sends `mentions: string[]` on `POST workorders/{id}/comments` when the composer contains encoded tokens. -- Highlights mentions in the comment thread using encoded tokens and/or `mentions` returned by the API. - -## Out of scope - -- Notification Center deep-linking for mention events. -- Backend notification triggers beyond the FE payload. - -## BE contract - -See `docs/work-orders/pending-be-contract.md` (Comments section): - -| Field | Status | -| ---------------------------------------- | -------- | -| POST `{ text, mentions?: string[] }` | FE ready | -| Response includes mentions for highlight | FE ready | - -Until BE confirms, encoded tokens in `text` preserve highlight behavior client-side. - -## Test plan - -- [ ] Open a work order detail → Internal tab → type `@` and pick a dispatcher from the list. -- [ ] Submit comment; verify POST body includes `text` with encoded token and `mentions` array. -- [ ] Reload detail; verify mention is highlighted in the thread (token and/or API `mentions`). -- [ ] Type `@` mid-word (e.g. email) — autocomplete should not open. -- [ ] Run `npm run verify`.