Pull Request Creation

Complete guide to creating pull requests in the Volare project with automated quality gates.

Overview

The /pr-create slash command automates pull request creation with built-in quality checks:

1. Rebase validation - Ensures branch is up-to-date with master
2. PHPStan analysis - Validates static analysis passes for PHP changes
3. Comprehensive PR description - Guides reviewers through changes

Quick Start

/pr-create

The command will:

1. Check if your branch needs rebasing
2. Check if PHPStan analysis is required (PHP files changed)
3. Create PR with comprehensive description
4. Link to related GitHub issue

Quality Gates

Gate 1: Rebase Validation

Purpose: Ensure your branch includes all changes from master.

What Happens If Failed:

⚠️  Master branch has advanced since your branch was created.

Please run `/rebase-master` first to rebase your branch onto the latest master.

Action Required: Run /rebase-master then retry /pr-create

Gate 2: PHPStan Analysis

Purpose: Ensure all PHP code passes static analysis.

Conditional Behavior:

• If no PHP files changed → Gate passes automatically
• If PHP files changed → Gate requires PHPStan validation

What Happens If Failed:

⚠️  This branch contains PHP file changes.

Please run `/fix-phpstan` first to ensure all PHPStan analysis passes.

Action Required: Run /fix-phpstan then retry /pr-create

Complete Workflow Examples

Backend PR with PHP Changes

# 1. Finish implementing feature
git add .
/commit "Implement booking validation service"

# 2. Create PR
/pr-create

# Output: ⚠️ Master has advanced...

# 3. Rebase onto latest master
/rebase-master

# 4. Retry PR creation
/pr-create

# Output: ⚠️ PHP files changed...

# 5. Run PHPStan analysis
/fix-phpstan

# 6. Commit PHPStan fixes
y

# 7. Create PR successfully
/pr-create

# Output: ✅ PR created: https://github.com/gocimit/volare/pull/123

Frontend-Only Changes

# 1. Finish frontend changes
git add .
/commit "Update flight search UI styles"

# 2. Create PR (no quality gates trigger)
/pr-create

# Output:
# ✅ Master is up-to-date
# ✅ No PHP files changed - skipping PHPStan check
# Creating PR...

Documentation-Only Changes

# 1. Update documentation
git add .
/commit "Update API documentation"

# 2. Create PR
/pr-create

# Output: ✅ PR created (no quality gates needed)

PR Description Template

The command generates this structure:

## Summary
[1-2 sentence overview]

## Changes Made

### What Changed
- [Specific change 1]
- [Specific change 2]

### Why These Changes
[Brief explanation]

## Testing

### Tests Added/Modified
- [Test 1 description]

### Manual Testing Performed
- [ ] [Test scenario 1]
- [ ] [Test scenario 2]

## Review Guidance

### Where to Start
1. Start with [file] to understand [concept]
2. Then review [file] for [logic]

### Focus Areas
- [Area 1]: [Why it needs attention]

## Related Links
- Related PR: #[number]
- Documentation: [link]

## Security Considerations
[Note any security implications]

## Breaking Changes
[Describe any breaking changes]

---
Closes #ISSUE_NUMBER

Best Practices

Before Running /pr-create

1. Commit all changes - Ensure working directory is clean
2. Run tests locally - Verify all tests pass
3. Review your changes - Do a self-review
4. Format code - Run Laravel Pint for backend changes

When Quality Gates Stop You

DO:

• Follow the recommended commands
• Fix issues identified by quality gates
• Retry /pr-create after resolving issues

DON’T:

• Skip quality gates unless necessary
• Force-push without running checks
• Create PRs with known analysis errors

Troubleshooting

”Master has advanced” Repeatedly

Cause: Your branch keeps diverging from master.

Solution:

1. Run /rebase-master to sync
2. Complete your work quickly
3. Consider syncing more frequently

PHPStan Finds Errors in Untouched Code

Cause: PHPStan analyzes all PHP files in the diff.

Solution:

1. Run /fix-phpstan on specific directory
2. Fix errors in files you modified
3. Escalate to team if errors exist elsewhere

Quality Gate Hangs or Times Out

Solution:

1. Check internet connectivity
2. Verify GitHub is accessible
3. Retry the command

Need to Skip for Urgent Hotfix

Solution:

1. Explicitly confirm to skip when prompted
2. Document in PR description why gates were skipped
3. Create follow-up issue for skipped checks
4. Get tech lead approval before merging

FAQ

Why is PHPStan required for PRs?

PHPStan catches type-related bugs at compile-time that would otherwise only appear in production. It enforces:

• Complete type hints
• Proper array type annotations
• Laravel best practices

Can I skip the PHPStan check?

Yes, but only by explicitly confirming. This should be rare and documented. Valid reasons:

• Urgent hotfix for production
• PHPStan false positive (document and create issue)

What happens if I push after gates pass?

Quality gates run at PR creation time. Additional commits:

• Won’t re-run quality gates
• Will trigger CI/CD checks
• May prompt reviewers to request re-check

Does PHPStan check run on frontend changes?

No. PHPStan only triggers when PHP files are detected in the diff.

How long does PHPStan check take?

• Initial analysis: ~30-60 seconds
• Automatic fixes: ~2-5 minutes
• Verification: ~30-60 seconds
• Total: ~5-10 minutes for typical PR

Related Documentation

• Slash Commands Reference - All commands
• Queue System - Queue infrastructure