grey-haven-pr-template

Grey Haven Pull Request Template

Create comprehensive, informative pull request descriptions that help reviewers understand the changes, context, and testing approach.

PR Structure (Standard Template)

Every pull request should follow this structure:

Summary

[Concise 2-4 sentence description of changes]

Motivation

[Why these changes are needed - business value, user impact, problem solved]

Implementation Details

[Technical approach, key decisions, trade-offs considered]

Testing

[Test strategy: unit/integration/e2e/benchmark, manual testing steps]

Checklist

Code follows Grey Haven style guidelines (90 char TS, 130 char Python)
Type hints added (Python) or types maintained (TypeScript)
Tests added/updated (unit, integration, e2e, benchmark)
Database migrations tested (up and down)
Multi-tenant isolation verified (tenant_id/RLS)
Pre-commit hooks passing
Documentation updated
No breaking changes (or documented with migration guide)

Section Guidelines

Summary

Purpose: Provide a brief, clear overview of what changed.

Guidelines:

2-4 sentences maximum
Focus on what changed from user/system perspective
Reference Linear issues: GREY-123
Mention multi-tenant or RLS changes
Use present tense

Example:

Summary

This PR adds magic link authentication using better-auth with email verification. Users can now sign in via emailed links instead of passwords. Addresses Linear issue GREY-234 and integrates with multi-tenant RLS policies.

Motivation

Purpose: Explain why these changes are necessary.

Guidelines:

Describe the problem being solved
Explain business value or user impact
Reference Linear issues: GREY-123
Include context not obvious from code
Mention technical debt or performance concerns

Example:

Motivation

Users reported frustration with password-based auth (GREY-234). Analytics show 35% abandon signup at password creation. Magic links offer passwordless auth, better security, reduced support burden, and built-in email verification.

Aligns with Q1 goal of improving onboarding conversion by 20%.

Implementation Details

Purpose: Explain how the changes work at technical level.

Guidelines:

Mention Grey Haven tech stack: TanStack Start/Router/Query, FastAPI, Drizzle, SQLModel
Reference Grey Haven patterns: repository pattern, multi-tenant RLS, server functions
Note database schema changes (snake_case fields, tenant_id, indexes)
Explain testing markers: unit, integration, e2e, benchmark
Include code references with file:line format

Example:

Implementation Details

Authentication Flow

Added magic link server function in lib/server/functions/auth.ts:45
Created email template with Resend integration
Implemented token verification route at /auth/verify

Key Changes

Server Functions: New sendMagicLink and verifyMagicLink with tenant context
Database Schema: Added magic_link_tokens table (snake_case, tenant_id, RLS)
Routes: Magic link verification page with TanStack Router navigation

Design Decisions

Token expiry: 15 minutes (security vs UX balance)
Single-use tokens with unique constraint
Tenant isolation via RLS policies
Email via Resend (better deliverability)

Testing

Purpose: Describe testing strategy and manual testing steps.

Guidelines:

List testing markers used: unit, integration, e2e, benchmark
Include manual testing steps
Mention test coverage
Note any edge cases tested

Example:

Testing

Automated Tests

Unit tests (18 new): Token generation, validation, expiry logic
Integration tests (6 new): Email sending, database operations
E2e tests (3 new): Full magic link flow with Playwright

Manual Testing

Request magic link from login page
Verify email received within 30 seconds
Click link in email
Verify successful auth and redirect
Test expired token (wait 16 minutes)
Test single-use token (use link twice)

Coverage

New code: 94% coverage
Critical paths: 100% coverage

Checklist

Use this checklist before requesting review:

Code follows Grey Haven style guidelines (90 char TS, 130 char Python)
Type hints added (Python) or types maintained (TypeScript)
Tests added/updated (unit, integration, e2e, benchmark)
Test coverage meets 80% threshold
Database migrations tested (up and down)
Multi-tenant isolation verified (tenant_id/RLS)
Pre-commit hooks passing (Prettier, Ruff, mypy)
Documentation updated (README, API docs)
No breaking changes (or documented with migration guide)
Linear issue referenced in description
Commit messages follow commitlint format
Virtual environment activated (Python projects)

Supporting Documentation

All supporting files are under 500 lines per Anthropic best practices:

examples/ - Complete PR examples

feature-pr.md - Feature PR example
bugfix-pr.md - Bug fix PR example
refactor-pr.md - Refactoring PR example
INDEX.md - Examples navigation

templates/ - Copy-paste ready templates

feature-template.md - Feature PR template
bugfix-template.md - Bug fix PR template
database-template.md - Database PR template

checklists/ - Pre-PR validation

pr-checklist.md - Comprehensive PR checklist

Special Cases

Breaking Changes

Always include migration guide:

Breaking Changes

BREAKING: User IDs are now UUIDs instead of sequential integers.

Migration Guide

Update API clients to handle UUID format
Run database migration: bun run db:migrate
Update any hardcoded user IDs in tests
Verify multi-tenant isolation still works

Timeline

Migration available: 2025-01-15
Required by: 2025-02-01

Database Migrations

Include up and down testing:

Database Migration

Changes

Add tenant_id column to organizations table
Create RLS policies for tenant isolation
Add index on tenant_id

Testing

✅ Migration up: Successful
✅ Migration down: Successful
✅ Data backfill: Verified for 1000+ records
✅ RLS policies: Tested with different tenants

When to Apply This Skill

Use this skill when:

Creating pull requests in Grey Haven projects
Reviewing pull requests for completeness
Onboarding new developers to PR standards
Creating PR templates for new repos
Documenting complex features or refactorings

Template Reference

These standards come from Grey Haven's actual templates:

cvi-template: TanStack Start + React 19
cvi-backend-template: FastAPI + SQLModel

Critical Reminders

Summary: 2-4 sentences - concise overview
Motivation: explain why - business value, user impact
Implementation: explain how - technical approach with file references
Testing: comprehensive - automated + manual steps
Checklist: complete - all items checked before review
Linear issues: reference - GREY-123 format
Multi-tenant: verify - tenant_id and RLS mentioned
Breaking changes: document - migration guide required
Database: test migrations - up and down
Code references: clickable - use file:line format