As Engineers, we often identify our ability to write and push code as our value to a company; documentation of an issue, commit, and/or pull request can easily become a – sometimes tedious – afterthought.
It’s no wonder why… most of us are used to working with non-technical people, in a culture that doesn’t protect us from them, that aren’t interested in the documentation of “the update that will fix the business” but rather updating it as quickly as possible and moving onto the next “update that will fix the business.” Unfortunately, this typically leads to bigger problems down the road.
Success is the sum of small efforts, repeated day in and day out.
At GiftStarter, we’ve built an engineering culture that is focused on sustainable feature updates, bug fixes, and releases. Right now we are an engineering team of three: Joel handles the platform and codebase, Valentine handles performance and code optimization, and I handle user experience and interaction design. We are spread across the world – Joel in Oregon, Val in Ukraine, and me in Florida – and must communicate very effectively in everything we do from issues to commits to – most importantly – pull requests.
Pull request template and easier code review
We’ve gone back-and-forth with a few different templates for our pull requests, but have landed on one (inspired by Sprint.ly).
It looks like this:
#### What's this PR do?
#### Where should the reviewer start?
#### How should this be manually tested?
#### Any background context you want to provide?
#### What are the relevant tickets?
#### Before/After Screenshots (if appropriate)
- **Is there a blog post?**
- **Does the knowledge base or Wiki need an update?**
- **Does this add new dependencies? Which ones?**
As Sprint.ly pointed out in their post, “Some sections get a “n/a”, such as the screenshot section for API only changes.”
Here’s what it looks like in practice: (view as a github gist)
Now, whether someone is merging code from 3,000 miles away, reviewing a pull request that was created in previous years, or checking out what code is about to be merged into their working branch, the viewer has consistent insight into the engineer’s thought process while changing the code base.
Again, put so well by Sprint.ly, “Just a little of the [engineer’s] time can save much more for the reviewer who often lacks context.”.
We love transparency at GiftStarter. Do you have any awesome-sauce that makes your development process more sustainable? Let us know!