What is a draft pull request?
A draft pull request in GitHub is essentially a work-in-progress that is not yet ready for final review. When you create a draft pull request, it signals to your teammates that the code is still in the preliminary stages and is open for initial feedback and discussion but is not yet ready for a detailed code review or merge into the main branch. This helps prevent premature reviews and keeps incomplete work from being accidentally merged.
What is a standard pull request?
In contrast, a standard pull request is considered ready for review. It's fully formed and typically signifies that the developer is satisfied with the submitted changes and is seeking final comments or approval before merging. This is the stage where code quality, functionality, and integration are rigorously evaluated by the team.
Key differences
- Readiness for review: Draft pull requests are not ready for final review, whereas standard pull requests are.
- Merge capability: You cannot merge a draft pull request until it has been marked as ready for review, changing its status to a standard pull request. Standard pull requests can be merged as long as all conditions, such as approvals and passing checks, are met.
- Visibility and status: Draft pull requests are visibly marked as drafts, making it clear that the changes are not finalized. This can help reduce noise in the repository by keeping unfinished work from being flagged as ready for merge.
Using Graphite's PR inbox
Graphite’s PR inbox enhances the management of pull requests by organizing them into customizable sections such as 'Needs your review,' 'Approved,' 'Drafts,' and 'Waiting for review.' For draft pull requests, Graphite creates a dedicated 'Drafts' section where all open drafts are automatically grouped. This feature helps you monitor and manage ongoing work without mixing it with more mature, review-ready pull requests. You can further customize these sections or create new ones to fit your team's workflow, and even share these configurations with teammates to ensure everyone is aligned.
Example workflow
Suppose you are working on adding a new feature but are not yet ready to receive full feedback. You might submit a draft pull request and label it appropriately in Graphite’s PR inbox. Your team sees it in the 'Drafts' section and can leave preliminary comments without the pressure of immediate final reviews.
Conversely, once your work reaches a more polished state, you can switch the pull request from draft to standard, moving it into the 'Waiting for review' section in Graphite, signaling that it's ready for a deeper inspection and potential merge.
Summary
Understanding the nuances between draft and standard pull requests and using tools like Graphite's PR inbox can ensure that every pull request is in the right stage and receives the appropriate attention at the right time. This clarity and organization can lead to improved collaboration and higher-quality software development.