Skip to content

docs(conventions): keep pr summaries to short plain-language bullets #353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zaxovaiko merged 3 commits into from
Oct 26, 2026
Merged

docs(conventions): keep pr summaries to short plain-language bullets #353

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
72a801f
docs(conventions): keep pr summaries to short plain-language bullets
zaxovaiko Oct 26, 2026
d1e4a1d
docs(conventions): cap pr summary at five bullets instead of requirin…
zaxovaiko Oct 26, 2026
855e6c7
docs(conventions): allow up to ten pr summary bullets for large prs
zaxovaiko Oct 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Summary

<!-- Outcome and scope in 1-2 sentences. Bare ticket key, no URLs. -->
<!-- Up to 10 short bullets (aim for 5 or fewer), one per change (a one-change PR gets one bullet), in plain sentences a reviewer reads in seconds: what the change does, not how. Details go in Why and Risks. Bare ticket key, no URLs. -->

## Why

Expand Down
2 changes: 1 addition & 1 deletion docs/standards/git-delivery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Detail for the delivery lines in `conventions`. Read this before committing, ope
- **No changeset in a feature or fix PR.** Do not run `pnpm changeset` or add `.changeset/*.md` alongside code. Changesets are written in their own PR once the work has landed and the release is being prepared, so the bump and summary describe the final state, not every iteration.
- **Green before review:** `pnpm verify` passes; `pnpm regen` after any contract/schema change.
- **Branch off `dev`; never commit directly to `dev`/`stage`.** Promotion chain `dev -> stage` + release tags. Never push without an explicit per-action confirmation, except the branch `/ship` opens its PR from.
- **PR description carries intent:** what / why / acceptance criteria / ticket key. Follow `.github/pull_request_template.md`; do not invent extra sections.
- **PR description carries intent:** what / why / acceptance criteria / ticket key. Follow `.github/pull_request_template.md`; do not invent extra sections. Keep the Summary to at most 10 short bullets (aim for 5 or fewer) in plain language, one per change (one bullet for a one-change PR), saying what it does rather than how; implementation detail goes in Why or Risks.
- **Diagram the flow.** A PR that adds or changes a flow across components (a request path through gates and ports, a state machine, an async job or webhook, a new module, port or table relation) fills the template's Diagram section with a Mermaid `flowchart` or `sequenceDiagram`. Name the nodes as the code does (routes, services, ports, tables), keep it under ~15 nodes, show the refusal and failure branches, not only the happy path. No flow (docs, deps, a one-file fix): delete the section.
- **No test plan or CI checklist in the description.** The `verify` and `commitlint` checks are already on the PR, so "typecheck clean", "159/159 passing" or "full gate passed" is noise a reviewer can see for themselves. Only write down verification CI cannot show: a manual walkthrough, a sandbox call against a vendor, a data migration run by hand.
- **No sensitive/internal data in titles, descriptions, or commits** - they are the public record. Bare ticket key (`ABC-45`), never the URL; no internal links, hostnames, secrets, PII. When in doubt, leave it out.
Loading