The Craftsmanship in Pull Requests

Software development is usually a highly collaborative process which comes with a unique set of challenges for any team when working towards a shared goal on the same code base, especially when working in parallel or even on the same file. A version control system such as Git is needed to ensure there are no code conflicts between the developers. 

Git is a highly popular Distributed Version Control System. This system is used to store source code and keep track of all changes made to the project. Additionally, since requirements change often, Git allows developers to revert and go back to an older version of the source code.

What’s a Pull Request?

A Pull Request is a collaborative process that lets a developer tell others developers about the changes they’ve made to a branch in a repository on Git. Once enough reviewers express their approval of the changes, these changes can be merged to the target branch. This creates an extra gate before the new code goes to the main code base, and ultimately gets deployed to production environment. This also enables developers to preemptively find bugs, optimizations or code related issues thus ensuring high quality applications are delivered to end users. This process is not an exact science however, so development teams usually adopt different policies depending on their needs.

Roles in a Pull Request

As an author, your responsibility is to create code that improves the code in the target branch. You should make it easy for reviewers to understand what is being changed and why.

As a reviewer, make sure that the code is correct before it gets merged into the target branch. Understand what the pull request is trying to achieve. Possibly be on the lookout for typos and code style problems. Feedback is always appreciated, so if you see something that can be done better, speak up! 

 “Sometimes this creates conflict”

Common problems:

• Excessive amount of PRs to review, which can slow down value delivery. This is especially problematic when working with agile methodologies.
• For certain Pull Requests, the review process can be frustrating when trying to understand the other developer’s code. 

Here are five key practices we follow at A.Y. Technologies, when authoring PRs.

Keeping Things Short

The larger the request, the longer it will take to review it. Beside that, a big Pull Request will require a lot of time from a reviewer and most likely require multiple reviews/comments.

What might also happen is that in the time between reviews, the author might have already moved on to something else. The change of focus is costly for the author as well as the reviewers. This can lead to a PR being up for review for multiple days, which could in turn negatively affect team morale as reviewing the same code multiple times is frustrating for everyone, not to mention the risk of requirements changing in the time it takes for a big PR to get approved and other potential merge conflicts. 

Keeping PRs short might sound like an easy fix, but in practice it involves being able to break down a problem while trying to solve it at the same time. To mitigate this, some companies have a limit on the number of lines changed for each PR. The exact number will depend on each team but the important part is balancing the sprint velocity (amount of work the team successfully completed during a sprint) against PR size.

Using description templates

This can almost be as effective as shortening your Pull Request!  To make a pull request as clear as possible, you need to include relevant information about the proposed code changes as well as testing details, description of a new feature and whether these changes break existing functionalities. 

Since this information is going to be useful for every PR, many web-based repositories offer description templates so that these checklists show up automatically in the description field every time a new Pull Request is made. You can find some examples here.

Adding visuals for added context

For front-end changes, when you can visually see what’s been changed it’s much easier to understand a PR’s intention. Using GIFs could be a quick and helpful way to see the changes in action. Also, consider adding designers to pull requests for these kinds of changes. They can review and give feedback to you while your code is waiting to be merged.

Commit messages

Commit messages can make auto-generated pull requests more useful, especially for smaller pull requests. Good commit messages can also provide a nice bullet-point-like summary of the code changes as well, and they help reviewers who read the commits in addition to the diff.

Limit the number of active PRs per author.

One of the problems developers face when working with agile methodologies is having to balance code reviews while also working on sprint tasks. This can result in Pull Requests piling up and staying un-reviewed for extended periods of time. 

In some cases this results in Pull Requests needing to be resolved during the last moments of the sprint in a rush to meet the team’s objectives. Enforcing a limited number of PRs per user gives developers an extra incentive to get their Pull Requests either merged or declined faster, since any extra changes would require the previous ones to have been resolved. Limiting the number of Pull Requests has some downsides however, since it can  block certain users from progressing with their tasks until their maximum number of PRs are approved or declined, which could be especially problematic when trying to push high priority code changes.

Conclusion

Pull Requests are an essential part of modern software development, but they can be a source of headaches when a company’s processes don’t handle them appropriately. I hope these tips can help your team cooperate more efficiently and achieve all your goals!