Pr Workflow

Pull Request Workflow

Purpose

A complete workflow for creating, developing, and submitting pull requests following project conventions.

Workflow Phases

Phase 1: Branch Setup

1. Ensure clean state:

   git status
   

2. Create feature branch:

   git checkout -b <type>/<description>
   

   Branch naming convention:

   • feat/<description> - New features
   • fix/<description> - Bug fixes
   • docs/<description> - Documentation
   • refactor/<description> - Code refactoring
   • test/<description> - Test additions/fixes

Phase 2: Development

1. Make changes following project conventions
2. Run quality checks:

   make lint
   make test
   

3. Fix any issues using lint-and-fix and test-and-fix skills

Phase 3: Pre-PR Verification

Before creating PR, run full verification:

1. Invoke verifier agent: Use the verifier subagent to run complete build → lint → test cycle

2. Review changes:

   git diff main...HEAD
   

3. Invoke code-reviewer agent (optional but recommended): Use the code-reviewer agent for quality assessment

Phase 4: Commit Changes

1. Stage files:

   git add <specific-files>
   

   Avoid git add -A - be explicit about what's committed.

2. Create commit:

   git commit -m "type(scope): description"
   

   Conventional commit types:

   • feat: New feature
   • fix: Bug fix
   • docs: Documentation
   • style: Formatting (no code change)
   • refactor: Code restructuring
   • test: Test changes
   • chore: Maintenance tasks

Phase 5: Create Pull Request

1. Push branch:

   git push -u origin <branch-name>
   

2. Create PR using gh CLI:

   gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
   ## Summary
   - Brief description of changes
   - Key implementation details
   
   ## Changes
   - List of specific changes made
   
   ## Testing
   - [ ] Unit tests pass
   - [ ] Lint checks pass
   - [ ] Manual testing done (if applicable)
   
   ## Related Issues
   Closes #<issue-number> (if applicable)
   EOF
   )"
   

PR Description Template

## Summary

[1-3 sentences describing what this PR does and why]

## Changes

- [Specific change 1]
- [Specific change 2]
- [Specific change 3]

## Testing

- [ ] All tests pass (`make test`)
- [ ] Linting passes (`make lint`)
- [ ] Build succeeds (`make build`)
- [ ] Manual testing completed (if applicable)

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated (if needed)
- [ ] No sensitive data committed

Quick Commands Reference

Troubleshooting

PR Checks Failing

1. Run make lint && make test locally
2. Fix any issues
3. Push fixes: git add . && git commit -m "fix: address PR feedback" && git push

Merge Conflicts

1. Fetch latest: git fetch origin main
2. Rebase: git rebase origin/main
3. Resolve conflicts
4. Continue: git rebase --continue
5. Force push: git push --force-with-lease

Converted and distributed by TomeVault — claim your Tome and manage your conversions.