How to Pull Request

Edu Depetris

- Sep 20, 2024
  • Pull Request
  • Playbook
  • Team Collaboration
  • Code Review
I’ve been writing and refining this guideline over many years, and it is now part of our playbook. Here are a set of practices, workflows, expectations, and more that I would like us to share and follow.

The Workflow

At Plum, we value developers who take ownership. This means that as a developer, you are responsible for the following:

  • You initiate pull requests (PRs)
  • Requesting reviews
  • Applying feedback
  • Merging the PRs once you receive approval
  •  Finally, you will monitor the changes to ensure they work as expected. If they do not, you are also responsible for rolling them back.

Creating a Pull Request

  • All code must be submitted through pull requests. Even small changes.
  • The PR title should reflects the work within, and a summary that helps to understand the context of the change.
  • Use helpful commit messages. This is a good guide: How to write a git commit message
  • Prepare it to be reviewed by a co-worker: 
    • If the PR contains UI changes, show before and after states with screenshoots and use boldly coloured arrows to show exactly what is being changed
    • Use Github comments to explain yourself.
    • (+1) We encourage you to use LOOM videos to introduce the new UI
    • (+1) We encourage you to use LOOM videos to explain a complex code.
  • Keep the PR up-to-date, and make sure it doesn't break anything once it gets into production.
  • Try keeping pull requests manageable. If 1,000 lines have changed in a pull request it can be quite difficult figuring out both how the pull request works and if there are any issues with it. Although of course sometimes large pull requests are inevitable. Just please don't submit large pull requests unless it's necessary.
  • ALWAYS add tests — If a PR doesn’t have associated tests, you should ask “is this testable?”.
  • Test PRs rigorously before requesting review.
  • Use Github Draft PR or mark the PR [WIP] in the title if you are working on something long term but want to use Github for incremental review.
  • Make sure to assign code reviewers or ask in Slack.
  • Be proactive: If something is urgent or has not been looked at for a while they can be posted in the squad’s slack channel or the #name-of-project channel as a friendly reminder.

Applying the received feedback to your Pull Request

  • Avoid force push commits when you’re applying feedback. it will overwrite history, disrupt reviews, lose comments, increase errors, reduce transparency, and complicate collaboration.
  • If there are significant changes required after the review, ask for another review of the changes back.
  • When you receive feedback in a form of Github Comment, do a quick initial response, even if it's just to acknowledge receipt.

Merging your Pull Request

  • Only merge your PR in once another team member has approved it. Individual teams may have different rules on number of reviewers etc.
  • in a perfect world, PRs don't get merged in until both tests and code style checks are green (CI).
  • Delete the pull request branch after it's been merged.
If you’re reviewing your PR in any environment like staging, PR-Branch or Production, then document the result in the associated Card.


Sometimes I don’t follow these guidelines 100%, to be honest. Every team or project ends up developing its own practices that work best for them. However, I believe this is a great starting point and makes our collaboration easier.

Happy Coding!