Pull Request Creation SOP

Version: 1.0.0 Last Updated: 2026-01-11 Status: Active

Overview

Purpose

This SOP guides developers through creating pull requests that follow project conventions. It covers all PR types (feature, bug fix, hotfix, release) with proper documentation, branch flows, and templates.

When to Use

ALWAYS: Creating any PR for the project SKIP: Draft PRs, WIP PRs (use GitHub UI directly)

Process Workflow

Flow Diagram

[Identify Type] --> [Analyze Changes] --> [Create Summary] --> [Submit PR]

Phase Summary

gh pr create

Quick Start

1. Ensure branch is ready: All changes committed, tests passing
2. Determine PR type: Feature, Bug Fix, Hotfix, or Release
3. Create PR: Use the appropriate template below
4. Fill template: Complete all sections
5. Request review: Assign reviewers

See Process Workflow for detailed steps.

PR Types & Decision Tree

Decision Tree

What are you merging?
  |-- Production release? (development -> main) -> [RELEASE PR]
  |-- Critical production fix? (urgent) -> [HOTFIX PR] (hotfix -> main)
  |-- Bug fix? (non-urgent) -> [BUG FIX PR] (bugfix -> development)
  |-- New functionality? -> [FEATURE PR] (feature -> development)

Quick Reference

feat: <description>

fix: <description>

hotfix: <description>

Release: <version>

Branch Naming Convention

• development

  or

  develop

  - Development branch (target for feature/bugfix PRs)

• main

  or

  master

  - Production branch (target for hotfix/release PRs)

Note: Verify your project's branch naming convention before creating PRs.

Phase 1: Analyze Changes

Step 1.1: Review Commit History

# Generic format
git log BASE..HEAD --oneline --no-merges

# Examples by PR type:
git log development..feature/my-feature --oneline --no-merges  # Feature PR
git log development..bugfix/my-fix --oneline --no-merges       # Bug Fix PR
git log main..hotfix/critical-fix --oneline --no-merges        # Hotfix PR
git log main..development --oneline --no-merges                # Release PR

# Get detailed commit messages
git log BASE..HEAD --pretty=format:"%s" --no-merges

# Count commits
git rev-list --count BASE..HEAD

Step 1.2: Analyze Code Differences

# View diff statistics
git diff BASE...HEAD --stat
git diff BASE...HEAD --shortstat
git diff BASE...HEAD --name-only

# Area-specific diffs (adjust paths to your project structure)
git diff BASE...HEAD --stat -- src/components/
git diff BASE...HEAD --stat -- src/pages/
git diff BASE...HEAD --stat -- src/store/

Step 1.3: Categorize Changes

Group changes by type:

• Features: New functionality
• Fixes: Bug corrections
• Refactors: Code improvements
• Infrastructure: Dependencies, config
• Tests: Test coverage
• Documentation: Docs updates

Phase 2: Create PR Summary

Step 2.1: Draft PR Title

Feature PR:

feat: Add AI assistant chat interface
Feature: Dark mode support

Bug Fix PR:

fix: Resolve navigation issue on page load

Hotfix PR:

hotfix: Prevent critical crash on startup

Release PR:

Release: v4.1.0 - AI Assistant & Dark Mode

Step 2.2: Draft PR Description

Use the appropriate template below.

PR Templates

Feature PR Template

## Summary
[Brief overview of feature]

## Changes
- Change 1
- Change 2

## Affected Areas
- [ ] Components/UI
- [ ] Pages/Views
- [ ] State Management
- [ ] Routing/Navigation
- [ ] Utils/Types
- [ ] API/Services

## Testing
[Describe testing performed]

## Related
- Issue: #XXX
- Ticket: XXX

Generated with [Claude Code](https://claude.com/claude-code)

Bug Fix / Hotfix PR Template

## Issue
[What was broken]

## Fix
[What was fixed]

## Root Cause
[If known and relevant]

## Affected Areas
- [ ] Components/UI
- [ ] Pages/Views
- [ ] State Management
- [ ] Routing/Navigation
- [ ] Utils/Types
- [ ] API/Services

## Verification
[How to verify the fix]

## Related
- Incident: #XXX
- Issue: #XXX

Generated with [Claude Code](https://claude.com/claude-code)

Release PR Template

## Release: v{version}

### Overview
[High-level summary of release]

### Features
- Feature 1 - [Brief description]
- Feature 2 - [Brief description]

### Fixes
- Fix 1 - [Brief description]
- Fix 2 - [Brief description]

### Improvements
- Improvement 1
- Improvement 2

### Affected Areas
- [ ] Components/UI
- [ ] Pages/Views
- [ ] State Management
- [ ] Routing/Navigation
- [ ] Utils/Types
- [ ] API/Services

### Testing Summary
[Summary of testing performed]

### Deployment Notes
[Any special deployment considerations]

### Breaking Changes
[If any, list here]

Generated with [Claude Code](https://claude.com/claude-code)

Phase 3: Create Pull Request

Step 3.1: Verify Prerequisites

Before creating PR:

# Run tests (use your project's test command)
npm test

# Type check (if TypeScript project)
npx tsc --noEmit

# Lint (use your project's lint command)
npm run lint

Step 3.2: Push Branch (if needed)

git push origin <branch-name>

Step 3.3: Execute PR Creation

Feature PR Example:

gh pr create \
  --base development \
  --head feature/user-settings \
  --title "feat: Add user settings page" \
  --body "$(cat <<'EOF'
## Summary
Implemented user settings page with preferences management.

## Changes
- Added UserSettings component
- Created settings state slice
- Added settings route

## Affected Areas
- [x] Components/UI
- [x] Pages/Views
- [x] State Management

## Testing
Verified settings page loads correctly and saves preferences.

## Related
- Ticket: #12345

Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Bug Fix PR Example:

gh pr create \
  --base development \
  --head bugfix/routing-issue \
  --title "fix: Resolve routing issue on page navigation" \
  --body "$(cat <<'EOF'
## Issue
Page navigation fails when accessing certain routes.

## Fix
Updated route parameter handling.

## Root Cause
Type mismatch between route params and page props.

## Verification
Navigate to affected page -> Should load correctly.

## Related
- Issue: #456

Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Release PR Example:

gh pr create \
  --base main \
  --head development \
  --title "Release: v2.1.0 - User Settings & Performance Improvements" \
  --body "$(cat <<'EOF'
## Release: v2.1.0

### Overview
Release adding user settings and performance improvements.

### Features
- User settings page
- Dark mode support

### Fixes
- Routing issue on page navigation
- State persistence fix

### Testing Summary
- All unit tests passing
- Manual testing completed

### Deployment Notes
[Any deployment-specific notes]

Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Quick Reference

Git Commands

# Review commits
git log BASE..HEAD --oneline --no-merges

# Review diffs
git diff BASE...HEAD --stat

# Push branch
git push origin <branch-name>

GitHub CLI Commands

# Install (macOS)
brew install gh

# Authenticate
gh auth login

# Create PR
gh pr create --base <target> --head <source> --title "<title>" --body "<body>"

# List PRs
gh pr list

# View PR
gh pr view <number>

Common Branch Flows

Troubleshooting

gh

brew install gh

gh auth login

git push origin <branch>

git branch -r

--body-file

Success Checklist

All PR Types

• PR type identified correctly
• Commit history reviewed
• Code diffs analyzed
• Affected areas identified
• PR title follows format
• PR description uses template
• Tests passing
• TypeScript passes
• Linting passes
• PR created successfully

Additional for Release PRs

• Version number verified
• All changes categorized
• Breaking changes noted
• Deployment notes included

Related Skills

/dev-feature

/review-code

/test

Note: Skill paths (

/skill-name

) work after deployment. In the template repo, skills are in domain folders.

End of SOP