Why You and Your Team Should Be Using Pull Requests
On August 11, 2015 by Rishi Mathur
image via flickr
Pull requests are awesome for fostering teams, giving teams a way to review code, learning from the requests, and starting new conversations about building great software. There’s a lot more that goes into pull requests than simply writing good code. Using pull requests to their full advantage means taking into account the most effective method while submitting pull requests with consideration to etiquette. It’s not like you’re going to a royal tea party or anything — but there are some best practices to keep in mind if you want to extract maximum benefit from pull requests on your team.
How do Pull Requests Work
For anyone unfamiliar with pull requests, they’re essentially a method of telling other GitHub users they made a misstep. So when you spot an error in someone else’s work, you can submit those errors to reviewers in a ‘pull request’.
The process starts by making a copy of the code within your local development environment, called a clone. Your alterations are made in the microenvironment, where a revision history is created so it can be easily tracked and reversed. The contributor decides when their changes are ready to be reviewed by the project maintainers, raising the ‘pull request’. The microenvironment changes are then submitted to the greater project, and if the changes are accepted, they will be included in the subsequent release.
Github is one of the most widely used programs for pull requests, but a few use Bitbucket to manage pull requests. Regardless of the pull request method, it’s always necessary to make changes public in the repository in order for your changes to be accessed by the project. It’s pretty easy and worth your while to get set up on sites like Github or Bitbucket.
Why Your Team Should Be using Pull Requests
Pull requests are like free mentoring sessions for you and your team. You’ll get nearly immediate feedback on your contribution, with the advantage of contributing to software used worldwide.
Pull requests and open source software encourage knowledge shares and promote discussion. Usually, even when requests are denied, developers will write with feedback explaining their decision. Therefore, even when you ‘lose’, you’re actually winning because you are learning a lesson from another developer. Code quality will undoubtedly improve as a result.
Working with pull requests encourages every member of the team to participate, even if it’s in a piece of a project they wouldn’t normally deal with. This team overlap is important to bring otherwise ‘disjointed’ parts of the team together to think about the software as a whole, and not just a piece.
There’s a sense of ownership that arises when everyone on a team has to review new code. It sets the bar for new code and fosters a shared responsibility, spurring team members to take their work seriously and preserve high quality code.
How to use Pull Requests Effectively for a Team
The shared repository model is a really great way to handle pull requests for small and large teams collaborating on private projects. You’ll have access to a single shared repository, as well as topic branches to isolate changes — making the process much simpler.
You’ll still be able to get code review (more eyeballs on your code), and discuss code alterations before transferring changes into a main branch. Depending on team size, it may be helpful to implement a protocol to determine who reviews what.
image via OpenHatch.org
Etiquette
Be Clear. The comment box exists for a reason; use it. It’s best to recreate both the problem and the changes for the reviewer to see. This way, the reviewer can envision your problem/solution more clearly and provide better feedback.
Keep it Small. Small, focused pull requests are your best shot that your pull request will be accepted. Anything that’s one big chunk will require a reviewer to take extra time out of their schedule in order to do so. Cumbersome pull requests will take longer to review, and in extreme cases will not be reviewed at all. Keep it under 12 files, don’t be too much of an overachiever.
Read Documentation. Usually you would read instructions before building something, but it’s astounding how many people just skip out on this part. For technical stuff and best practices, take a look at the documentation. It’s there, so why not use it?
Copy and Paste is for Lazy People and Bugs.There can be all kinds of other issues with copy and pasting, such as unseen spaces that computers can be finicky about. Copy and paste usually creates more problems, so if you feel like you want to do a quick copy & paste, just don’t do it.
Communicate. Always send feedback, don’t try to just fix the mistake yourself. The point is to start discussions and promote learning, so don’t shortchange anyone — including yourself. And always be polite. People make contributions to help on a project, so foster interactions that are supportive and encouraging.
Pull requests play an important role in code review, and encourage a team to work together for a common goal. In that process, you get free mentorship: score. It’s a win-win situation for everyone involved, and in the end you’ll come up with much better software.
Originally published at blog.jixee.me on August 11, 2015.
