How to suggest changes in a GitHub pull request

When reviewing code in a GitHub pull request (PR), you might find areas that could benefit from modification or clarification. Suggesting changes directly within the PR can accelerate the review process and enhance code quality. In this guide, we'll go over how to suggest changes in a GitHub PR using GitHub's code review features, as well as look at how Graphite's PR inbox can streamline these interactions.

Proposing changes to a pull request

GitHub offers several tools within its interface to propose changes to a pull request:

1. Single-line suggestions: During a PR review, you can navigate to the "Files changed" tab to comment on specific lines of code. To suggest a specific change, click on the line number to highlight it, then click the "+" icon that appears to the right of the code line. GitHub will open a comment box where you can type your suggestion. For a straightforward change, use the "Suggest changes" button in the toolbar of the comment box, which wraps your suggested code in a markdown format that GitHub recognizes for applying changes directly.

2. Multi-line suggestions: If your suggestion spans multiple lines, GitHub supports this as well. Click and drag over the range of lines you want to suggest changes for, then proceed as with a single-line suggestion. This feature is especially helpful when you need to propose changes that extend beyond simple one-liners, such as adjustments to function implementations or modifications to multiple lines of a configuration file.

3. Adding a suggestion via comment: You can also add suggestions through the PR's discussion thread without selecting specific lines. Use markdown to format your code block with the "suggestion" syntax. This method is useful when your suggestion does not directly modify existing lines but perhaps adds new ones.

Using Graphite's PR inbox to manage suggestions effectively

Graphite's PR inbox transforms how developers handle pull requests (PRs) by offering a structured, email-like interface. This system organizes PRs efficiently, helping you concentrate on those that need your attention and making the review process smoother. Here’s how you can use Graphite's PR inbox to manage suggestions more effectively:

1. Organized review sections: Graphite automatically categorizes PRs into sections such as "Needs your review," "Approved," "Returned to you," "Merging and recently merged," "Drafts," and "Waiting for review." This helps you prioritize your actions and keep track of PRs at different stages of the review process.

2. Customization and sharing: You can customize your PR inbox by creating new sections with specific filters or edit existing ones to better suit your workflow. This customization includes rearranging the order of the sections to match your preferences.

3. Enhanced search capabilities: Graphite supports a robust search function within the PR inbox, allowing you to perform fuzzy searches across PR titles, descriptions, authors, and more. This feature is accessible directly from the inbox or via the cmd + k shortcut, making it easy to find the PRs you need without unnecessary navigation.

4. Integration with Git: Graphite’s CLI and VS Code extension further integrate the PR inbox with your Git workflow, making it easy to manage stacked pull requests. Stacking PRs makes them easier to read, write, and manage, which is ideal for teams aiming to ship high-quality software swiftly.

Graphite's PR inbox not only enhances the review process by organizing suggestions and changes but also promotes better collaboration through shared settings and advanced search tools. By leveraging these features, teams can ensure that no suggestion goes unnoticed and that every PR is reviewed with the necessary attention to detail.

Best practices for suggesting changes

• Be clear and concise: When proposing changes, be as specific as possible. Provide context or reasoning for your suggestions to help the author understand your perspective.
• Use code formatting: Leverage GitHub’s markdown formatting to make your suggestions clear and easy to apply. This reduces misunderstandings and simplifies the implementation of suggested changes.
• Follow up: After making suggestions, check back on the pull request to see if further clarification is needed or if there are new comments from the PR author.

By using GitHub's suggestion features effectively and leveraging tools like Graphite's PR inbox, teams can enhance their code review practices and maintain higher code quality standards. This process not only saves time but also encourages a collaborative development culture.