Introduction

This document describes how we use Pull Requests at Township, and what comprises a well-formed PR.

Pull Requests at Township

The purpose of a PR is to provide a summary/preview of the work that has been done to those doing code review for a feature, bug fix, code change, etc.

A PR should consist of as many of the following as needed:

• Title
  • Start with a feat, fix or chore tag (conventional commit style)
  • Match the Linear ticket title somewhat, if possible
  • Tag drafts with WIP so its apparent the PR is not yet ready to be reviewed.
• Description
  • Summary of the reason for the change/new feature/bug
  • Summary of the approach taken, reasoning behind engineering decisions
  • Summary of what your change/feat/fix accomplishes
• Loom video/Screen Recording
  • Demo of the changes, walkthrough, setup, etc.
  • Try to keep this under a couple mins or less.
  • Use a screen recording if no verbal explanation is needed and it is something quick.
• Screenshots
  • Highlight before/after of a UI addition/fix/update etc.
  • Add label to screenshot
• List of files added
  • Ex: adding a bunch of icons may look like a lot of code has been added when in reality it’s just a lot of new files. It could be helpful to list those in the PR description so the code reviewer knows those may not need to be looked at in detail
• Links
  • to Figma if its a UI ticket
  • to Linear - especially if the project is not synced with Linear
  • to newly added dependencies
  • to reference articles used

Pull Request Process at Township

Submitting PRs

When you push your first commit from a branch, Github will display a banner with a button to open a new pull request. You then need to fill in the PR description and submit it as a Draft PR or Ready for Review PR.

Draft PRs

• start a draft when you’ve pushed up some code but aren’t ready for final review
• start writing the full PR description, update as progress is made/commits are added
• maybe include to-do items
• include blockers/what you’re having trouble with & need help on
• link to the PR in the project slack channel to draw attention to it if help is needed