Skip to content

Pull Request Workflow

This guide covers the end-to-end process for creating, reviewing, and merging pull requests in the FCC project. It includes setup for AI-assisted development with Claude Code, branch protection configuration, and the step-by-step review and merge process.

Overview

The FCC project follows a feature branch workflow:

graph LR
    A[main] -->|branch| B[feature/your-change]
    B -->|commit| C[Push to origin]
    C -->|CI runs| D{Tests pass?}
    D -->|yes| E[Review PR]
    D -->|no| F[Fix & push again]
    F --> D
    E -->|approve| G[Merge to main]
    G --> A

Step-by-Step: Creating a Pull Request

1. Create a Feature Branch

Always branch from the latest main:

git checkout main
git pull origin main
git checkout -b feature/your-change-description

Use descriptive branch names following this convention:

Prefix Use case Example
feature/ New functionality feature/phase-6-api-layer
fix/ Bug fixes fix/registry-loading-edge-case
docs/ Documentation only docs/add-deployment-guide
refactor/ Code restructuring refactor/simulation-engine

2. Make Your Changes

Implement your changes, following the code style conventions and testing requirements.

3. Verify Locally

Before pushing, always run:

source .venv/bin/activate
make lint    # Must pass with no issues
make test    # All tests must pass, coverage >= 99%

4. Commit

Write clear, descriptive commit messages:

git add <specific-files>
git commit -m "Short summary of what and why

Longer description if needed. Focus on the 'why' rather than
the 'what' — the diff shows what changed."

Commit Hygiene

  • Stage specific files rather than git add . to avoid accidentally committing secrets or build artifacts.
  • Keep commits focused on a single logical change.
  • Reference issue numbers where applicable (e.g., Fixes #42).

5. Push and Create the PR

git push -u origin feature/your-change-description

Then create the PR using the GitHub CLI:

gh pr create \
  --title "Short descriptive title (under 70 chars)" \
  --body "$(cat <<'EOF'
## Summary
- What this PR does and why

## Files Changed
- Key files and what changed in each

## Test Plan
- [ ] `make lint` passes
- [ ] `make test` passes (all tests, >= 99% coverage)
- [ ] Manual verification steps if applicable
EOF
)"

Or create the PR through the GitHub web UI at the link git prints after pushing.

Step-by-Step: Reviewing and Merging a PR

For Solo Developers (No Required Reviews)

If you are the sole maintainer and branch protection does not require reviews:

Option A: Review and Merge via GitHub CLI

# View the PR details
gh pr view <number>

# Check CI status
gh pr checks <number>

# Once CI passes, merge
gh pr merge <number> --merge

Option B: Review and Merge via GitHub Web UI

  1. Navigate to the PR on GitHub (e.g., https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/pull/1)
  2. Click the Files changed tab to review the diff
  3. Verify the Checks section shows all CI jobs passing (lint + test matrix)
  4. Click Merge pull request (select "Create a merge commit" for full traceability)
  5. Click Confirm merge
  6. Optionally click Delete branch to clean up the feature branch

After Merging

Update your local repository:

git checkout main
git pull origin main

For Teams (Required Reviews)

If branch protection requires approvals, a different team member must review and approve before merging. See Branch Protection Setup below.

AI-Assisted PR Workflow with Claude Code

When using Claude Code to implement changes, the AI operates under your GitHub credentials. This means:

  • PRs created by Claude Code are authored by you
  • GitHub does not allow you to approve your own PRs
  • If branch protection requires reviews, you need a second reviewer
sequenceDiagram
    participant You
    participant Claude as Claude Code
    participant GH as GitHub

    You->>Claude: Describe the task
    Claude->>Claude: Implement changes
    Claude->>Claude: Run tests & lint
    Claude->>GH: Create feature branch
    Claude->>GH: Push & create PR
    Claude-->>You: PR URL
    You->>GH: Review diff in Files Changed
    You->>GH: Verify CI checks pass
    You->>GH: Merge PR
    You->>Claude: (optional) Pull and continue

Enabling Automated PR Approval

If you want Claude Code (or any automation) to be able to approve PRs, you need a separate GitHub identity to act as reviewer. There are three approaches:

Create a second GitHub account to act as your project's reviewer bot.

  1. Create the bot account at github.com/signup using a different email address (e.g., yourname+bot@gmail.com)
  2. Create a Personal Access Token (PAT) on the bot account:
    • Go to Settings > Developer settings > Personal access tokens > Fine-grained tokens
    • Select the repository
    • Grant permissions: Pull requests: Read and write
    • Generate and save the token
  3. Add the bot as a collaborator:
    • In your repo, go to Settings > Collaborators > Add people
    • Add the bot account with Write access
    • Accept the invitation from the bot account

  4. Use the bot token for approvals:

    # Store the bot token (do NOT commit this)
export GH_BOT_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

# Approve a PR using the bot identity
GH_TOKEN=$GH_BOT_TOKEN gh pr review <number> --approve \
  --body "CI passes. LGTM."

# Merge (using your own credentials)
gh pr merge <number> --merge

Security

Never commit bot tokens to the repository. Store them in environment variables or a secrets manager. Add .env to .gitignore if you use a dotenv file.

Approach 2: GitHub App

For organizations or more robust setups, create a GitHub App that can act as a reviewer.

  1. Create a GitHub App at Settings > Developer settings > GitHub Apps
  2. Grant Pull requests: Read and write permission
  3. Install the app on your repository
  4. Use the app's installation token to approve PRs

This approach is more secure than a bot account because tokens are short-lived and scoped.

Approach 3: Disable Required Reviews

For solo projects where you are the only contributor, the simplest option is to not require PR approvals:

  1. Go to Settings > Branches > Branch protection rules
  2. Edit the rule for main
  3. Uncheck Require a pull request before merging, or
  4. Keep the PR requirement but uncheck Require approvals

This still gives you the PR workflow (feature branch, CI checks, diff review) without the approval gate.

Branch Protection Setup

Branch protection rules enforce quality standards on the main branch. Configure them at Settings > Branches > Add branch protection rule.

Setting Value Reason
Branch name pattern main Protect the default branch
Require a pull request before merging On Forces feature branch workflow
Required approvals 0 Solo developer cannot self-approve
Require status checks to pass On CI must pass before merge
Status checks: lint Required Ruff linting
Status checks: test (3.10) Required Test matrix coverage
Status checks: test (3.11) Required Test matrix coverage
Status checks: test (3.12) Required Test matrix coverage
Status checks: test (3.13) Required Test matrix coverage
Require branches to be up to date On Prevents merge conflicts
Include administrators Off Allows you to merge without approval
Setting Value Reason
Required approvals 1+ At least one peer review
Dismiss stale reviews On Re-review after new pushes
Require review from code owners On If using CODEOWNERS file
Include administrators On No bypassing for anyone

Setting Up Status Checks

After your first PR triggers CI, the status check names become available:

  1. Go to Settings > Branches > Branch protection rules
  2. Edit the main rule
  3. Check Require status checks to pass before merging
  4. Search for and add: lint, test (3.10), test (3.11), test (3.12), test (3.13)

Merge Strategy

The project uses merge commits (not squash or rebase) for traceability:

gh pr merge <number> --merge
Strategy When to use
Merge commit (default) Standard feature PRs -- preserves full commit history
Squash merge Many small fixup commits that should be one logical change
Rebase merge Linear history is preferred and commits are already clean

Quick Reference

# === Creating PRs ===
git checkout -b feature/my-change     # Create branch
# ... make changes ...
make lint && make test                 # Verify locally
git add <files> && git commit          # Commit
git push -u origin feature/my-change   # Push
gh pr create --title "..." --body "..."  # Create PR

# === Reviewing PRs ===
gh pr view <number>                    # View PR details
gh pr checks <number>                  # Check CI status
gh pr diff <number>                    # View the diff

# === Merging PRs ===
gh pr merge <number> --merge           # Merge commit
gh pr merge <number> --squash          # Squash merge
gh pr merge <number> --rebase          # Rebase merge

# === After Merge ===
git checkout main && git pull          # Update local main
git branch -d feature/my-change       # Delete local branch