Asynchronous agile

View Original

Pull requests

Pull requests are a  feature that most source control systems provide (GitLab calls it a “merge request (MR)”). This feature allows anyone who wants to contribute code to a project, to package their changes so someone else can review their code before merging it into the codebase. In theory, it’s a systemic approach to facilitate code reviews.

While PRs are controversial for the delays they introduce in the system, they are a popular feature. If your team follows this practice, then use it as a way to communicate your changes effectively to facilitate code review and feedback. Here are some good practices you must follow.

  • Communicate purpose clearly. Explain not just what has changed, but why. For example, if you’re adding new functionality, reference the user story you’re implementing.

  • Use integrations with your task board. For example,  Jira’s integrations with GitHub, GitLab and BitBucket make it easy to reference the tickets in question.

  • Explain your implementation, especially if some parts of it may not be clear by just examining the code. Use videos, sketches, or diagrams to clarify your explanation. Ideally, these should already be part of the task on your task board.

  • If you’re reviewing a PR, be respectful when providing feedback. Do your best to understand before you offer suggestions. Help the author understand the rationale behind your suggestions. 

  • If you’re the author of the request, be open to feedback - this is your chance to not just improve your code, but also to create a healthy engineering culture. 

  • PRs are notorious for the lag they introduce. Reviewers and authors need to collaborate with each other in a thoughtful and timely fashion so you keep the waiting time minimal. Track PR pickup time (the time a PR spends waiting for someone to start reviewing it) and review time (the time it takes to complete a code review and merge the code). Low pickup times and review times are indicators of a healthy collaboration and feedback culture. 

  • Be pragmatic about pull requests. Not every merge needs a full-blown code review. Tools like gitStream allow developers to merge small and safe code changes with an auto-approval. You can specify rules for higher risk changes – such as to go through a specific reviewer or to go through more than one reviewer.

To learn more about writing effective PRs, read Keavy McMinn’s article about writing pull requests

See this content in the original post