7. Pull Request Strategies - Choosing Your Approach
Learning Objectives
By the end of this section, you will:
- Understand the GitHub Flow workflow for repository management
- Compare micro and macro PR approaches
- Learn when to use different PR strategies
GitHub Flow Overview
This project uses the GitHub Flow model for managing changes. This workflow helps maintain code quality and collaboration through systematic pull requests (PRs).
Understanding Pull Request Strategies
When contributing to a project, you'll need to choose between two main PR approaches:
1. Micro PRs (Small, Frequent Changes)
Characteristics:
- Single task or feature per PR
- Usually < 200 lines of code
- Frequent submissions
Advantages:
- Easier to review: Small changes are easier for reviewers to understand and provide feedback on.
- Less risk: If a problem arises, it's easier to identify and fix because the change is isolated.
- Faster feedback loop: Frequent PRs mean more opportunities for feedback and improvement.
Challenges:
- Overhead: Each PR requires its own review and merge process, which can be time-consuming.
- Context switching: Frequent changes can disrupt the flow of work, especially if developers have to switch between different tasks.
2. Macro PRs (Large, Comprehensive Changes)
Characteristics:
- Multiple related changes
- Larger codebase modifications
- Less frequent submissions
Advantages:
- Efficiency: Larger PRs can be more efficient because they require fewer reviews and merges.
- Coherence: By grouping related changes together, it may be easier to understand how different parts of the codebase interact.
Challenges:
- Difficult to review: Large changes can be overwhelming for reviewers, making it harder to catch issues.
- Higher risk: If a problem arises, it can be more difficult to identify and fix because it could be anywhere in the large set of changes.
- Delayed feedback: With fewer PRs, there are fewer opportunities for feedback.
Practical Guidelines
When to Use Micro PRs
- Bug fixes
- Small feature additions
- Documentation updates
- Performance optimizations
When to Use Macro PRs
- Major version upgrades
- Complex feature implementations
- Architectural changes
- Large-scale refactoring
Update Scenarios
The choice between micro and massive PRs can significantly impact the workflows in our Patch Update, Release Update, and Major Version Update.
Patch and Release Updates: These updates typically involve minor changes or additions, which can be easily managed with either micro or massive PRs. The choice depends on your team's preference for review speed and context switching.
Major Version or Large Jump Release Updates: These updates require a thorough review of every single control and requirement. They also necessitate extensive testing, both automated (via the CI/CD testing matrix) and manual. In this scenario, the overhead of managing multiple micro or mini PRs can be substantial. However, the benefit is that it allows for more granular control and review of changes. It's also easier to isolate and fix issues that arise during testing.
Practice Exercise
Consider these scenarios and decide which PR strategy you would use:
- Fixing a typo in documentation
- Implementing a new security control
- Upgrading to a new major version
Summary
- Choose micro PRs for better review quality and reduced risk
- Use macro PRs for cohesive, large-scale changes
- Consider project context and team preferences
- Balance efficiency with maintainability
Review Questions
- What are the key differences between micro and macro PRs?
- Which PR strategy would you choose for a critical security patch?
- How does GitHub Flow support different PR strategies?
Why not both?
One approach is to have the small feature branches get merged into a version branch on successful review following the "Micro PR" approach. Then you can do a more holistic review of the macro PR associated with the version branch focusing more on having a consistent coding style, ensuring no duplicate inputs got created, identifying InSpec controls that weren't modified when similar ones were, etc. Once the version branch is approved, it can be merged into the main branch and a release can be cut.