The Art of the PR

The Art of the PR is less about a lofty art form and more about a personal process I've developed for making pull requests. It's been shaped by years of experimentation and, perhaps more importantly, by the pushback and thoughtful reviews of my teammates, for which I'm deeply grateful, even when this felt frustrating. This process isn't fixed; it's meant to evolve alongside new teammates and their changing preferences, as well as shifts in my own personality and work style.

I think of a PR much like a potter or sculptor might think of their work. It is an artifact, a concrete representation of the effort and thinking that went into improving the software. It's not just a mechanism for change but also a historical record and a space for experimentation and intellectual exchange. That's only possible, of course, when teammates trust one another and are willing to engage honestly in the process. As a proponent of trunk-based development, I prefer PRs that are short and focused, addressing one problem cleanly. Yet I also recognize that rules exist to serve the software, not the other way around. Sometimes the best thing you can do is break them. A concise, well-scoped PR gives the review process the clarity it needs to extract the final bits of quality that might otherwise be lost in a tangle of changes.

The Process

1. Start with a problem and brainstorm solutions. Every PR begins with a clear problem to solve. I explore solutions freely at this stage — there are no bad ideas. The goal is to generate possibilities without judgment, trusting that clarity will emerge as I iterate.

2. Make a branch early and commit aggressively. I create a branch as soon as possible and commit ideas frequently. Commit points are chosen based on my own sense of where I might want to "roll back" if I take a wrong turn. This habit gives me flexibility and captures the evolution of my thinking.

3. Open a draft PR to track the journey. I like to open a draft PR early in GitHub and follow along with the work as it develops. This step is optional, but I find it helpful for keeping the process visible and giving teammates a sense of where things are headed.

4. Self-review as if you were someone else. Once the PR starts to fulfill the requirements of the task, I do a self-review. I try to approach my code like any other reviewer would — leaving comments on decision points and clarifying my reasoning. If something is important or potentially confusing, I'll elevate that explanation from a comment in the PR to documentation in the codebase itself.

5. Write the description and supporting context early. While the code is still in progress, I often take breaks to draft the PR description and add supporting documentation. These drafts change as the work evolves, but the act of writing helps me clarify my own thinking and check whether my approach still makes sense. It's as much a tool for me as it is for my teammates now or in the future.

6. Ask for review before perfection. At this point, I invite my teammates to review the work. Ideally, everyone understands that a PR is never truly "final." There's always room for improvement and the occasional mistake. I believe striving for perfection too early slows us down unnecessarily and hurts momentum.

7. Encourage thoughtful feedback. This is the moment for teammates to flex their attention to detail and share ideas. There are still no bad suggestions. I rely on automated tools like linters to handle formatting so comments can focus on substance, not style.

8. Iterate and resolve feedback. From here, it's a matter of addressing my own comments and my teammates' feedback, iterating until the PR feels solid.

9. Merge when ready and leave a clear trail. Once I've completed my review and at least one teammate has approved, it's time to merge. A strong PR at this stage tells the story of the work through a handful of meaningful commits, a description that explains why the changes were made, and comments that capture alternative paths we considered. And critically, the PR should always be fully roll-backable if something goes wrong.

Conclusion

While this process might sound heavy-handed, with a little practice it becomes second nature and usually quite fast. More importantly, I've found that approaching pull requests this way pays off enormously: it sharpens my own thinking, aligns the team around shared decisions, and leaves behind a rich record of how and why our software evolved.

But beyond those tangible benefits, there's something more subtle but just as valuable: this process transforms PRs from a transactional step in the development cycle into a creative and collaborative ritual. It's a place where ideas are tested, assumptions are challenged, and collective craftsmanship is practiced. Done well, a pull request isn't just a vehicle for shipping code. It's a space where a team refines how it thinks and works together.

And that, to me, is the real art of the PR.