PR Merge Strategies for PostgreSQL Extensions

pr-merge-strategies.md

PostgreSQL Extension Development: Pull Request Merge Strategies

TL;DR

Squash is often preferred since features are typically cohesive units. However, if commits represent distinct logical steps (e.g., "add function," "add tests," "optimize"), rebase preserves that structure.

Branch Feature Development

1. Publish Branch pushes your local branch to the remote repository (GitHub) for the first time
2. After publishing, continue making commits locally and push to update the remote branch
3. Publishing doesn't merge into main—the branch remains separate until explicitly merged
4. You can publish early to enable CI checks or collaboration while continuing development

Pull Request Code Review Process

1. Create the PR on GitHub

   • Select your branch and target branch (main)
   • Add description explaining changes
   • Optionally request specific reviewers

2. Review Phase

   • Reviewers examine code, leave comments/questions
   • You respond to feedback and push additional commits as needed
   • CI/automated checks run (if configured)
   • Discussion continues until reviewers approve

3. Approval

   • Reviewers explicitly approve the PR
   • All requested changes addressed
   • CI checks passing (if required)

Merge Process

Once approved, click "Merge pull request" with one of these options:

Merge Commit (default)

Pros:

• Preserves complete history with all individual commits
• Shows exactly when branch was integrated via merge commit
• Easy to revert entire feature by reverting merge commit

Cons:

• Creates non-linear history that can be cluttered with many feature branches
• Includes all "work-in-progress" commits, typo fixes, etc.

Squash and Merge

Pros:

• Clean, linear history on main—one commit per feature
• Hides messy development process (WIP commits, fixes)
• Easier to navigate git log and git blame

Cons:

• Loses granular commit history from development
• Individual commit metadata (timestamps, intermediate states) gone
• Makes bisecting bugs within a feature harder

Rebase and Merge

Pros:

• Linear history while preserving individual commits
• Each commit appears as if developed directly on main
• Maintains logical development steps for complex features

Cons:

• Rewrites commit SHAs (breaks references if branch shared)
• Can create confusion if commits weren't meant for main individually
• More complex to revert—must revert each commit

Post-Merge

After merging, the branch can be deleted (GitHub offers this option automatically).