To draft a pull request in GitHub, you utilize a specific option within the pull request creation interface that explicitly sets its status as a "draft," indicating it's a work in progress and not yet ready for review or merging.
Understanding Draft Pull Requests
A Draft Pull Request is a powerful feature in GitHub that allows developers to share their ongoing work without formally requesting reviews. It serves as an early indicator of work in progress, enabling transparency and collaboration from the very beginning of a feature's development cycle. Unlike a standard pull request, a draft PR cannot be merged and typically doesn't trigger review requests, signaling that the code is still under active development.
Step-by-Step Guide: Drafting a Pull Request
Creating a draft pull request is a straightforward process on GitHub. It typically follows pushing your changes to a new branch and then initiating a pull request from that branch.
Prerequisites
Before you can draft a pull request, ensure you have:
- Pushed your local changes to a new branch on your GitHub repository.
- Navigated to your repository on GitHub's web interface.
The Drafting Process
Follow these steps to create a draft pull request:
- Navigate to Your Repository: Open your repository on GitHub.
- Access Pull Requests: Click on the "Pull requests" tab located in the repository's navigation bar.
- Initiate a New Pull Request:
- If you've recently pushed a branch, GitHub will often display a banner at the top prompting you to "Compare & pull request" for that branch. Click this button.
- Alternatively, click the "New pull request" button.
- Select Branches: On the "Compare changes" page, choose your base branch (where you want to merge your changes) and your compare branch (your feature branch containing the new code).
- Create the Draft:
- Fill in the title and description for your pull request.
- Instead of directly clicking the green "Create pull request" button, observe the button's options.
- Use the drop-down and select "Create Draft Pull Request".
- Finally, click the "Draft Pull Request" button to confirm.
Once created, your pull request will appear with a clear "Draft" badge, indicating its status. You can convert it to a regular pull request by clicking the "Ready for review" button when your work is complete.
Important Note for Organizations
If you are a member of an organization, there might be specific access controls or policies in place. You may need to request access to draft pull requests from an organization owner if you encounter any permissions issues or if the option is not available to you.
Benefits of Using Draft Pull Requests
Draft pull requests offer several advantages that enhance collaboration and workflow efficiency:
- Early Feedback: Share work-in-progress to get initial thoughts, architectural suggestions, or design feedback from teammates without the pressure of a formal review.
- Work in Progress (WIP) Indication: Clearly signals that the code is not yet complete, preventing premature merges or reviews.
- Transparency: Keeps the team informed about ongoing development, even before a feature is fully implemented.
- No Accidental Merges: A draft pull request cannot be merged until it's explicitly marked as "Ready for review," ensuring code quality and preventing incomplete code from reaching the main branch.
- Continuous Integration (CI) Checks: Still allows CI/CD pipelines to run on the draft, providing early insights into potential issues or broken tests.
Draft vs. Ready-for-Review Pull Request
Understanding the key differences helps in deciding when to use each type:
| Feature | Draft Pull Request | Ready-for-Review Pull Request |
|---|---|---|
| Status Badge | Clearly marked as "Draft" | No "Draft" badge; typically "Open" or "Ready for Review" |
| Review Requests | Cannot formally request reviews until converted | Can formally request reviews from team members |
| Automatic Merging | Cannot be merged automatically or manually until converted | Can be merged (if all checks pass and approvals met) |
| Purpose | Work in progress, early sharing, discussion | Complete, ready for final code review and merge |
| Notifications | Fewer immediate notifications to reviewers | Notifies assigned reviewers of readiness for review |
Practical Tips for Draft PRs
To maximize the effectiveness of draft pull requests:
- Use Descriptive Titles: Even for a draft, a clear title helps others understand what you're working on.
- Link to Issues: If your PR relates to an issue, link it in the description to provide context.
- Utilize Checklists: Add a checklist in the description to track progress and indicate what's left to do.
- Ask Specific Questions: If you're looking for feedback on a particular aspect, mention it explicitly in the description or comments.
- Convert When Ready: Once your code is complete and stable, remember to convert the draft PR to "Ready for review" to initiate the formal review process.
