Pull Requests

# ===== A PR is a proposal =====
# A pull request says: 'here is a branch; consider merging it'.
# It's the unit of code review on GitHub, GitLab, Bitbucket.

# ===== Open a PR =====
gh pr create --title 'feat: add tax field' --body 'Adds tax to Order model'
gh pr create --draft
gh pr create --web    # open browser

# Or push to a branch and the host shows a 'create PR' link.

# ===== PR template =====
# .github/pull_request_template.md
## Summary
- What changes and WHY

## Test plan
- [ ] Unit tests pass
- [ ] Manual test on staging
- [ ] No console errors

## Screenshots (UI changes)
<!-- attach -->

## Related issues
Closes #123

# Auto-fills new PRs; helps reviewers know what to look for.

# ===== Draft PRs =====
# Open as draft when work-in-progress; CI runs but it isn't ready to merge.
# Mark Ready for review when done.

# ===== Conventions =====
# Title: type(scope): subject  (Conventional Commits)
#   feat(orders): add tax field
#   fix(login): handle empty password
#   docs(readme): clarify install
#
# Body:
#   What + WHY (not just what)
#   Test plan
#   Linked issues
#   Screenshots for UI

# ===== Code review etiquette =====
# Author:
# - Self-review BEFORE marking ready
# - Small PRs (< 400 lines diff)
# - Respond to every comment
# - Re-request review after fixes
# Reviewer:
# - Block on correctness; suggest on style
# - Use 'suggestion' blocks for inline diffs:

\`\`\`suggestion
const total = subtotal + tax;
\`\`\`

# - Be kind; ask why, suggest how
# - Approve when ready; request changes when not

# ===== Merge strategies =====
# Squash and merge: one commit on main; cleanest history (most teams)
# Rebase and merge: linear history; preserves individual commits
# Merge commit: preserves branch shape; can clutter

# Pick one strategy + enforce via branch protection.

# ===== Branch protection =====
# Require:
# - PR review (1+ approvals)
# - All status checks pass
# - Up-to-date branch before merge
# - Linear history (no merge commits)
# - Signed commits

# ===== Auto-merge =====
gh pr merge --auto --squash
# Merges automatically when all checks pass + reviewers approve.

# ===== Merge queue =====
# Sequentially merges PRs, retesting each against latest trunk.
# Prevents 'race' merges where each PR is green individually but breaks main combined.

# ===== Useful commands =====
gh pr list
gh pr view 123
gh pr checkout 123
gh pr diff 123
gh pr review 123 --approve
gh pr merge 123 --squash --delete-branch
gh pr close 123

# ===== Patterns =====
# - Conventional Commit titles
# - Templates with summary + test plan
# - Small PRs; reviewable in 10 minutes
# - Auto-merge + merge queue for busy teams
# - Branch protection on default branch

# ===== Pitfalls =====
# - Mega-PRs (> 1000 lines) -> hard to review properly
# - 'LGTM' without reading
# - No template -> inconsistent context
# - Mixing styles (squash + merge commits) -> messy history

gh pr create --title 'Fix login' --body 'Closes #42'
gh pr view
gh pr merge --squash