This guide is divided into three essential sections to help you effectively manage pull requests in a collaborative project:
- Create a Pull Request: This section explains how to properly prepare and submit a pull request (PR) to ensure that your changes are well-documented, easy to review, and aligned with project goals.
- Review a Pull Request: Learn the best practices for providing constructive feedback, identifying potential issues, and ensuring code quality during the review process.
- Respond to a Pull Request Review: Understand how to address reviewer feedback, make necessary changes, and ensure your pull request meets the required standards for approval.
By following these steps, you will contribute to a smooth and efficient workflow, ensuring collaboration and quality in your project.
Before creating a pull request, first, please follow the GitHub Workflow to create and push your branch.
On GitHub, go to the main page of the repository where you’ve pushed your branch.
From the "Branch" menu, choose the branch that contains your changes (the one you just pushed).
You’ll see a button labeled Compare & pull request. Click this to begin the process of creating a pull request for your changes.
{ loading=lazy, width="800" }
/// caption
///
In the pull request form, type a descriptive title for your PR. Provide a detailed description of the changes you've made, why they are important, and any other relevant information.
{ loading=lazy, width="800" }
- If your pull request is ready for review, click Create Pull Request.
- If you want to create a draft version of the pull request for further work before it's ready for others to review, click the drop-down and select Create Draft Pull Request, then click Draft Pull Request.
{ loading=lazy, width="350" }
/// caption
///
{ loading=lazy, width="800" }
/// caption
///
In the list of pull requests, click the pull request that you'd like to review.
{ loading=lazy, width="800" }
/// caption
///
In the pull request page, click Files changed so as to see the changes.
{ loading=lazy, width="600" }
/// caption
///
2.3.1 by clicking 
{ loading=lazy, width="20"}, you can choose the unified or split view.
{ loading=lazy, width="600" }
/// caption
///
When hovering over the lines of code, you can click the blue comment icon to add your review comments.
{ loading=lazy, width="800" }
/// caption
///
2.4.1 If you'd like to add a comment on multiple lines, please click the line number of the first line you want to add comments and drag down to select a range of lines.
If you'd like to suggest a specific change to the lines, click 
{ loading=lazy, width="20"}, and then edit the text within the suggestion block.
{ loading=lazy, width="600" }
/// caption
///
If you'd like to comment on a file, click 
{ loading=lazy, width="20"} at the right top of the file, then add your comments.
{ loading=lazy, width="500" }
/// caption
///
After you finished reviewing a file, you can mark it as viewed.
{ loading=lazy, width="600" }
/// caption
///
When you're done, click Start a review. If you have already started a review, please click Add review comment. !!! note "Notice" All line comments are pending and only visible to you. You can edit the comments when needed. If you'd like to abandon your review, please go to in Review changes and click Abandon review
Click Review changes, and then type comments to summarize your proposed changes.
{ loading=lazy, width="500" }
/// caption
///
{ loading=lazy, width="600" }
/// caption
///
- Select Comment: Provide general feedback on the changes without explicitly approving or rejecting them.
- Select Approve: Indicate that you’ve reviewed the changes and approve them for merging. A common comment for simple approvals is "LGTM" (Looks Good to Me).
- Select Request changes: Provide feedback indicating that revisions are needed before the changes can be approved.
Current review round is done; this publishes your comments and suggestions. Then the PR can either be merged or updated (depending on approval or comments). We generally expect that whoever submits the PR will merge once all feedback has been incorporated or otherwise addressed.
Navigate to your repository name, click Pull requests
{ loading=lazy, width="600" }
/// caption
///
After receiving feedback on your pull request, you can apply the changes in one of two ways: either by committing each change individually or by grouping several changes into a single commit. The method you choose depends on whether you prefer fine-grained control over the commit history or a more streamlined approach, which also allows for grouping related changes for easier review.
If you agree with a suggested change, apply it in the "Conversation" tab by selecting "Commit suggestion" to create a separate commit for it. This approach helps keep your commit history clear and each change traceable.
{ loading=lazy, style="width:100%" }
This button will bring up a "Commit suggestions" box in which you can update the commit message with something informative about why this change is being made. Please see the GitHub Repo Guide section on commits for more guidance on how to write a good commit message.
If you plan to include multiple changes in one commit, you can add suggestions to a batch. This is the preferred method when multiple suggestions are needed to implement the full change. First, navigate to the "Files changed" tab.
{ loading=lazy, style="width:100%" }
/// caption
///
As you scroll through the updated files, comments and suggestions will be displayed at the line(s) to which they refer. Select the option to "Add suggestion to batch" for all suggestions you wish to include; use the "Remove from batch" option to remove those you do not want to include.
{ loading=lazy, style="width:45.5%" }
{ loading=lazy, style="width:45%" }
Once you've collected all the desired suggestions, click "Commit suggestions" at the top of the tab, then select "Apply suggestions", to commit them all in one go. Observe that the number of selected suggestions appears in both these buttons (5 in this example). All the suggestions to commit can be scrolled through in this pop-up.
{ loading=lazy, style="float:right;width:75%" }
{ loading=lazy, style="width:75%" }
In the commit message field, enter a brief, descriptive message that clearly explains the reasoning for the changes made to the file(s). For instance, the above changes might best be served by the following commit message, since a function's behavior has been changed.
Change expected output to match new function return
Please see the GitHub Repo Guide section on commits for more guidance on how to write a good commit message.
After entering your commit message, click the "Apply Suggestions" button to finalize the commit and thus save your modifications to the repository. This step ensures that your changes are recorded and can be reviewed or merged into the main codebase.
Once you have addressed all the requested changes, click the "re-request review" button to notify the PR reviewer(s). This action prompts them to evaluate your updated code and provide feedback or approval.
{ loading=lazy, style="width:60%" }
If the suggested change falls outside the scope of your pull request, create a new issue to address the feedback separately. Issues can be created directly from a PR comment by clicking on the three dots in the top right corner of the comment and selecting "Reference in new issue".