exupero's blog

Drafting pull requests

I've used a few different workflows for creating pull requests. On one project I liked to create an empty pull request as soon as I created a new branch. In it I accumulated any to do's, testing instructions, and other information that came up during development. In part that practice was due to heavy pair programming, in which the PR description served as a communication channel between developers, but it was also a project where features and bugfixes were well-defined and most branches were destined to become pull requests.

Later I changed projects and the new environment was different. The team wasn't as comfortable with in-progress PRs, we didn't do as much pair programming, and branches were often so experimental they wouldn't get merged. In that environment I stopped accumulating info in PR descriptions and put it instead in a set of Markdown files on my local machine.

That habit has waxed and waned over time. On longer projects with more continuity from one pull request to the next, it's much easier to remember what information is relevant for reviewers and keeping notes isn't as necessary. Also, as changesets are more focused, reviewers don't need as much information. Where more documentation is required, it's commonly captured somewhere other than the PR description, such as in a ticketing system or wiki, both of which are easily referenced from a pull request.

Currently, though, I'm back to drafting PRs in local Markdown files. When I spawn a new Git worktree, I also create a template pr.md file with some YAML frontmatter that specifies the target branch, PR title, what labels to attach, and who should review the PR. The template also contains prompts for additional information, such as testing instructions. When it's time to create a pull request, I call a script that invokes the GitHub API and creates a PR with the given title and description, then assigns reviewers and attaches labels.

My template pr.md asks a series of questions whose answers usually come up during work on a branch, and it's occasionally so much information that it can be hard to remember it all when creating a new PR. Rather than trying to keep it all in mind, pr.md gives me a private place to capture and reorganize information before opening a pull request.