From 156e7ca2df43b4c3d16a24b704536a8da747a16a Mon Sep 17 00:00:00 2001 From: Julien Gautier Date: Thu, 30 Apr 2026 23:03:13 +0200 Subject: [PATCH] chore: add PR template and document title/body convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Formalise the PR-flow conventions while we install the PR-flow itself. .gitea/pull_request_template.md auto-populates the PR body in Gitea with five sections: Summary / Motivation / Implementation notes / Verification (with CI-gate checkboxes + ADR/diagram update flags) / Related. Sections can be left blank when irrelevant; the template guides without adding ceremony. Header HTML comment reminds the contributor of the PR title format and links to the full convention. docs/development.md §5 (Conventional commit cycle) gains a 'PR conventions' subsection that: - explains why the PR title format matters (squash-merge subject on main, validated by commitlint in the CI 'commits' job) - separates feature-branch commit hygiene (exploratory OK) from PR title hygiene (must conform) - documents the type vocabulary (feat/fix/docs/style/refactor/perf/ test/build/ci/chore/revert) - proposes an optional scope vocabulary (apps, libs, cross-cutting domains like decisions/docs/ci/deps) - describes the body template No new ADR. The PR title format is derived from ADR-0007 (Conventional Commits at the commit-msg layer) plus ADR-0015 (squash-merge means PR title becomes the commit subject on main). The body template is tactical guidance, not architectural. --- .gitea/pull_request_template.md | 30 ++++++++++++++++++++++ docs/development.md | 45 +++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+) create mode 100644 .gitea/pull_request_template.md diff --git a/.gitea/pull_request_template.md b/.gitea/pull_request_template.md new file mode 100644 index 0000000..85df9db --- /dev/null +++ b/.gitea/pull_request_template.md @@ -0,0 +1,30 @@ + + +## Summary + +## Motivation + +## Implementation notes + +## Verification + +- [ ] `pnpm ci:check` green locally +- [ ] `pnpm ci:audit` green (or pre-existing drift acknowledged) +- [ ] Tested manually: +- [ ] Architecture diagram updated (if `docs/architecture.md` was affected) +- [ ] ADR amended or added (if a decision changed) + +## Related diff --git a/docs/development.md b/docs/development.md index 5d4ee93..6817bb7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -249,6 +249,51 @@ pnpm ci:perf # production build + Lighthouse CI against the static-served 5. To cut a release: tag `vX.Y.Z` on `main`. The `release.yml` workflow will pick it up (currently a stub; populated alongside the on-prem deploy ADR). +### PR conventions + +The squash-merge subject on `main` is the **PR title**, not the individual commits on the feature branch (those collapse into the squash). Two practical consequences: + +1. **The PR title must itself be a valid Conventional Commits message.** Same format as a commit message — `(): `, imperative mood, lowercase, no trailing period, target ≤ 70 chars. The CI `commits` job (commitlint on the PR commit range) catches violations. +2. **Individual commits on the feature branch can be exploratory.** The local `commit-msg` hook still validates each commit's format, but the squash makes granular history irrelevant on `main`. Granular history stays available in the PR for review. + +#### Type vocabulary + +| Type | When | +| ---------- | ----------------------------------------------- | +| `feat` | new user-facing feature or capability | +| `fix` | bug fix | +| `docs` | documentation only (no code) | +| `style` | formatting / whitespace (no logic change) | +| `refactor` | code change that is neither a fix nor a feature | +| `perf` | performance improvement | +| `test` | tests added or updated | +| `build` | build system, dependencies | +| `ci` | CI configuration | +| `chore` | maintenance, scaffolding, project metadata | +| `revert` | revert a previous commit | + +#### Scope vocabulary (optional) + +| Scope | Examples | +| ------------- | ----------------------------------------------------------- | +| App | `portal-shell`, `portal-bff` | +| Lib | `shared-tokens`, `shared-ui`, `shared-util`, `feature-auth` | +| Cross-cutting | `decisions` (ADR work), `docs`, `ci`, `deps` | + +Scope is optional. Omit when the change spans too many areas to scope cleanly (e.g., a workspace-level rename). + +#### PR body template + +When a PR is opened against `main`, Gitea pre-populates the body from `.gitea/pull_request_template.md`: + +- **Summary** — 1–3 bullets describing what changed. +- **Motivation** — why, with ADR / issue / incident links. +- **Implementation notes** — trade-offs, alternatives considered, follow-ups deferred. +- **Verification** — CI gates checked, manual test description, ADR / diagram update flags. +- **Related** — ADR-XXXX, related PRs, follow-up issues. + +The template guides without enforcing — sections can be left blank when irrelevant. The point is to make "what does the reviewer need to know" explicit, not to add ceremony. + --- ## 6. Where to look