Commits & PRs

This guide explains how we name commits, document pull requests, and merge changes so the repository stays traceable, auditable, and easy to navigate.

---

Commits

Format

<type>(<scope>): <summary>

• Use only the title line for normal commits (no body or footer required).
• <summary> must be ≤ 100 characters.
• Use an imperative, lowercase summary (for example, fix(cart): handle empty id).
• Split unrelated work into separate PRs so each squash commit on main tells one focused story.
• Branch commits are ephemeral. Only the squash commit survives on main. Keep branch commits organized enough for review, but do not require polished individual commits.
• Do not merge or leave wip: or placeholder commits as the reviewed branch history. Use git commit --fixup and interactive rebase to clean them up before requesting review or merging.
• For breaking changes, add BREAKING CHANGE: in the PR description or, if using a body, in the commit body so automated changelogs can identify it.
• Keep structural refactors separate from behavior changes unless the behavior change depends on the refactor.

Allowed Types

Type	Description
feat	A new feature for the user or the system.
fix	A bug fix.
docs	Documentation changes only (Markdown, JSDoc, guides).
style	Code style changes (formatting, spacing, semicolons) with no logic impact.
refactor	Code changes that improve structure without changing behavior.
perf	Performance improvements.
test	Adding or adjusting tests only.
build	Changes to build system, dependencies, or tooling.
ci	CI/CD configuration or automation changes.
chore	Maintenance tasks that do not affect src or tests (for example, scripts).
revert	A revert of a previous commit.

Scope Examples

• cart, orders, products, router, queries, stores, components, pages, utils, ci, deps.
• Scopes must align with existing directories or domain concepts. Do not invent ad-hoc scopes. For example, prefer stores or auth over misc.

Examples

feat(cart): add optimistic add-to-cart
fix(router): guard against NaN id
refactor(queries): centralize productLine keys

For more details on the commit message format, see Conventional Commits.

Branch Names

• Use <type>/<short-description> in lowercase kebab-case (for example, fix/auth-session-reset).
• Include an issue or ticket identifier when the repository workflow requires it.
• Keep one coherent change per branch.

Tooling

• Add commitlint to the project to enforce these rules locally.
• Combine commitlint with Husky pre-commit and commit-msg hooks. Use lint-staged for staged-file checks, as described in 10.Lint-Format.
• Use git commit --fixup and interactive rebase to clean up branch history when useful. These tools affect the PR branch only. The squash commit remains the permanent record on main.

---

Pull Requests

PR Title

• Follow the Conventional Commit format without a PR-number placeholder.
• Example:

feat(cart): add optimistic add-to-cart
fix(auth): reset session on logout

PR Workflow

• Open PRs as Draft PRs by default.
• Draft PRs still need a meaningful title and initial description so reviewers can track context from day one.
• Do not request formal review until CI passes.
• Keep the PR as a Draft when checks fail. If you need reviewer help with a failing check, or a failure already exists on the target branch, explain the exception in the description.
• Once the developer considers the work ready, move the PR to Ready for Review.
• At that point, assign at least 2 reviewers.
• If the change involves Product or Design, invite them to the review.
• Product Managers and Designers are encouraged to leave comments in the PR thread, explicitly stating whether they approve or request changes.
• Treat their feedback as part of the review process.

Chained PRs

• For dependent work, set the next PR's base branch to the branch of the preceding PR. This keeps the diff focused on the new work.
• After the preceding PR merges, rebase the downstream PR branch onto the current target branch before requesting review or merging.

PR Description Must Include

• Intent of the change (1–3 sentences).
• Link to the related issue in your tracker (Jira, Trello, GitHub Issues, GitLab Issues, or another tracker).
• Use auto-closing keywords (Fixes #123, Closes #123) when linking issues so merges close them automatically.
• Key points of change (bulleted).
• The review focus: approach or architecture, correctness, deployment safety, or another specific concern.
• Known uncertainty and time sensitivity, if any.
• Test results and screenshots when relevant.
• Include a screen recording when it demonstrates a flow, UI change, or interaction more clearly than screenshots.
• Breaking changes, if any.
• If dependencies are added or updated, explain why, note any security considerations, and apply the dependencies label.
• Recommend adding and using .github/PULL_REQUEST_TEMPLATE.md to keep this checklist consistent across PRs.

Example

## Intent
Add optimistic cart updates so the cart responds before the server confirms the request.

## Related issue
Fixes #123

## Changes
- Update the cart mutation.
- Handle rollback when the request fails.

## Review focus
Please review correctness and deployment safety. The rollback path is uncertain.

## Testing
- `pnpm test`
- Manual checkout flow

PR Labels

• Use labels to provide quick context about the PR.

Label	Use for
feature	New functionality.
bug	Bug fixes.
refactor	Internal refactors.
documentation	Documentation updates.
test	Tests added or updated.
performance	Performance-related changes.
chore	Maintenance, cleanup, or dependency changes.
ci	CI/CD pipeline changes.
breaking-change	Changes that introduce a breaking change.
hotfix	Urgent production fixes.
needs-review	PRs awaiting code review.
work-in-progress	PRs that are not ready to merge.
security	Authentication, authorization, or vulnerability-related changes.

PR Size

• Keep PRs focused and ≤ 400 LOC diff (tests excluded). Split if larger.
• Small PRs produce small squash commits, which keep git bisect precise and reverts safe.

Review Comment Conventions

Format review comments as <label> [decorations]: <subject>, followed by optional context and next steps.

Use these labels:

• suggestion — propose a specific improvement and explain why.
• issue — identify a concrete problem or risk; include a suggested fix when possible.
• nitpick — request a trivial preference change; it is always non-blocking.
• question — ask for clarification or investigation when the concern is uncertain.
• praise — call out sincere, specific work that is effective.
• thought — share a non-blocking idea or learning opportunity.

Use (blocking) when the concern must be resolved before the PR can merge. Use (non-blocking) when it must not delay acceptance. Use (security) for security-related context when useful. Keep decorations sparse. (typo) is optional if the team needs to distinguish copy corrections from other nitpicks.

Decorations express review intent. They do not automatically trigger the platform’s Request Changes action. A security-related comment may be blocking or non-blocking depending on its impact.

Keep comments clear, respectful, specific, and actionable. Use question when reporting uncertainty instead of presenting an unverified concern as fact.

Example:

issue (blocking,security): This path accepts unsanitized HTML.

Explain the risk and required resolution in the discussion. Record the disposition after the discussion, then resolve the thread when the concern is addressed or the decision is documented.

See Conventional Comments for the complete specification and communication guidance.

Review Process

• At least 2 reviewer approvals.
• CI (lint, typecheck, tests) must be green before merge.
• When Product or Design is involved, their approval in the PR thread is required before merge.
• When requesting another review, summarize what changed since the previous review and identify any unresolved questions.
• Acknowledge every review comment with a response, an appropriate reaction, or an explicit resolution. Acknowledgement does not require a code change.
• Aim for at most two rounds of review comments per reviewer. Beyond that, move the discussion to a direct conversation or the team’s agreed synchronous channel.
• Summarize the decision and any resulting changes in the PR before merging.
• Warn likely reviewers before opening a time-sensitive or unusually complex PR.
• Changes that affect multiple teams or carry significant operational risk need sufficient stakeholder review before merge.
• Share the PR link in the agreed review channels when asking for feedback so everyone stays aware. If email notifications slip through, ping reviewers directly without public call-outs.
• Unless a change is critically wrong and must be fixed before merging, reviewers should avoid using the Request Changes action.
• Leave feedback as regular comments so the author can review and address it.
• The Request Changes option blocks merging. Casual use can create unnecessary friction.
• Use it only when the PR cannot move forward without a mandatory correction, such as a security flaw, broken build, or severe architectural violation.

Developer checklist (before pushing)

• Run lint, type-check, and test suites locally to catch issues before CI.
• Prefer rebasing the PR branch onto the current target branch to resolve conflicts and keep history current. Merge the target branch instead when the repository workflow requires it.
• Verify screenshots, recordings, and documentation are up to date with the change.
• Use git commit --fixup and interactive rebase for branch-history cleanup when needed.
• Keep structural refactors separate from functional changes unless they are required for the same implementation.

Merging changes

• Squash merge is mandatory.
• Merge every PR as a single commit.
• The commit message must include the PR number at the end for traceability.
• By default, reuse the PR title for the squash commit and append (#<PR_NUMBER>).
• Developers may adjust the squash commit message at merge time if needed, but the PR number is always required.
• Each PR produces exactly one commit on main. Split unrelated changes into separate PRs to preserve change-level granularity.
• Revert a squash-merged PR with git revert. Reference the original PR number in the revert message, for example: revert: feat(cart): add optimistic add-to-cart (#456).

Examples (squash commit messages)

feat(cart): add optimistic add-to-cart (#456)
fix(auth): reset session on logout (#789)

---

Rationale

• Squash merge keeps main linear and easy to scan. Each PR becomes one commit, while branch-level implementation commits remain an authoring and review detail.
• PR numbers in commit messages preserve traceability between Git history and GitHub/GitLab PRs.
• Conventional Commits enable consistent automation for release notes and changelogs.
• Commitlint ensures that commit messages follow the required format before they reach the repository.
• Draft PRs allow early feedback while making it clear that the work is not ready to merge.
• Green CI before formal review prevents reviewers from spending time on failures that authors can resolve first.
• Review context and change summaries help reviewers focus their feedback and reduce repeated work.
• Comment acknowledgement keeps review discussions clear and shows which feedback the author has addressed.
• Assigned reviewers (2+) ensure accountability and shared code ownership.
• Product and Design participation ensures that functional and UX concerns receive review alongside technical concerns.
• PR labels help triage, filter, and prioritize changes quickly.
• Screen recordings reduce back-and-forth in reviews and make UI and UX changes clearer.