The Dos and Don'ts of GitHub Pull Requests

With over 100 million active users, GitHub has become an essential online workspace for countless software developers worldwide. One of the fundamental aspects of GitHub's collaboration process is the Pull Requests feature, which enables developers to propose changes to a codebase and have them reviewed by peers before being merged into the main codebase.

At Watermelon, we strive to enhance the code review process by providing business logic context to GitHub Pull Requests. In this article, we will outline the essential Dos and Don'ts of GitHub Pull Requests to help developers make the most of this powerful collaboration feature.

What Is GitHub Pull Request?

GitHub Pull Request is a GitHub feature that allows developers to propose changes to a codebase and have them reviewed by others before merging the changes into the main codebase.

A GitHub Pull Request, or PR for short, allows developers to compare new code in a comfortable UI, as shown here.

Reviewers may also comment on code, or over the whole PR, allowing two way communication with the proposing developer. This helps a lot with standardizing code and helping your team understand what your thought process. The rich Markdown system allows media such as videos and images, helping you get a point across.
‍

Admins may even set conditions to stop merging if not met, allowing safer deployments.

Dos and Don'ts of GitHub Pull Requests

In this section, we will delve deeper into the best practices and common mistakes to avoid when creating a GitHub Pull Request, outlining the Dos and Don'ts to ensure a successful review and merge process.

Do’s

1. Ensure code readiness: Before creating a pull request, make sure that your code is ready for review. This means that your code should be complete, linted, well-documented, and free of syntax errors and bugs. Your code should also follow the coding standards of the project you are contributing to. If your code is not ready for review, you will waste the time of the reviewers and delay the merge process.

2. Write a clear and concise pull request description: The pull request description is where you explain the changes you have made and the reasons behind them. Make sure your description is clear and concise and provides enough context for the reviewer to understand the purpose of the changes. If your pull request is addressing a particular issue, make sure to reference that issue in your description. You can also use Watermelon to automate this process.

3. Break your changes into small, focused commits: When making changes to a codebase, it is best to break them into small, focused commits. Each commit should contain a single logical change, and the commit message should describe that change in a clear and concise manner. This makes it easier for reviewers to understand the changes you have made, and it also makes it easier to revert changes if necessary.

4. Respond promptly to feedback: When your pull request is being reviewed, be sure to respond promptly to any feedback you receive. If a reviewer requests changes, make those changes as soon as possible and update your pull request. This shows that you are responsive and committed to the project.

Don'ts

1. Don’t make unnecessary changes: When creating a pull request, make sure that you are only changing the code that is necessary to address the issue at hand. Don't make changes to unrelated code or add features that are not relevant to the issue being addressed. This can make it more difficult for reviewers to understand the changes you have made and can delay the merge process.

2. Don’t ignore feedback: When you receive feedback on your pull request, don't ignore it. Even if you don't agree with the feedback, it is important to engage in a constructive dialogue with the reviewer. If you have a different opinion or approach, explain your reasoning and try to find a compromise that works for everyone.

3. Don’t merge your own pull request without approval: Even if you have created a pull request, you should not merge it into the main codebase without approval from a reviewer. This ensures that changes are properly reviewed and tested before they are merged into the main codebase. If you merge your own pull request without approval, you risk introducing bugs and breaking the codebase.

4. Don’t ignore project guidelines: Do not ignore the guidelines and best practices established by the project you are contributing to. This includes coding standards, documentation requirements, and review processes. Ignoring these guidelines can result in rejected pull requests and delays in the merge process. Be sure to familiarize yourself with the project's guidelines and adhere to them when contributing.

Watermelon

The image below provides an example of a GitHub pull request that was made to update the Watermelon backend. It showcases the Watermelon Context App, which indexes and presents relevant information for new pull requests, Jira tickets, Slack message threads, and even summarizes the Pull Request using WatermelonAI.

As you can see, the pull request includes a summary of the changes made and provides context for why those changes were made.

The Watermelon Context App streamlines the pull request process by providing easy access to relevant information and minimizing the need to switch between different tools and platforms. This helps to improve collaboration among team members and ensure that changes are reviewed thoroughly and efficiently.

Conclusion

In this article, you have learned about the Dos and Don'ts of creating a GitHub Pull Request. By following these guidelines, you can ensure that your pull requests are effective, efficient, and well-received by the project community.

Additionally, if you're looking for ways to streamline your code review process, consider checking out the Watermelon Context GitHub Action. With this powerful tool at your disposal, you can enhance your code review process and make it even more effective. Don't wait - try it out today!

‍