Write Merge Requests Like Youre Posting to Instagram

Merge requests (or pull requests) are a huge part of a team's development process. It's the main gatekeeper preventing developers from throwing whatever they want into the default branch. It's also a reference to the history and understanding of the changes someone is making to an application, giving code reviewers and testers more confidence in really knowing what's going on.

So what does it have to do with Instagram? Bear with me here, it has merit.

The foundations of an Instagram post

This can apply to any social media platform, but we're going to stick with Instagram here. Let's start with an example of a post from NASA, which can be broken down into a few vital components: an image, description, and hashtags.

https://www.instagram.com/p/BwH0GRAjL5i/

What does this have to do with code?

I'm getting there! Looking at each part, we can start to relate these back to our merge request. Starting with the 3 basics:

• Image => Code
• Description => What is your feature?
• Hashtags => What parts of your application does this impact?

Code

Just as much as the image or video is the most important aspect of a post, so is your code. It's the primary content that's driving the conversation and interest. While it's strong on its own, without context it can create its own set of issues.

Description

In NASA's post above, without seeing the description, this could very well be a blurry illustration of the Death Star. Instead, thanks to the description, we find out it's Jupiter, where the infrared imaging allows us to get a better look at its atmosphere.

Not knowing what the code you're looking at does or what it impacts can lead to confusion and a lack of understanding for those not already familiar with your application. Even for veterans, only being able to see a small segment of a diff when compared to a giant codebase completely changes what you're looking at.

Areas of Impact

Just as hashtags allow people to tag content to show the topics it's related to, providing an area of impact helps give your reviewer an idea of where they should be paying attention. If the reviewer or tester only knows of one location a changed component is used (when it's used more broadly throughout the application), they're potentially missing important use cases that may have breaking changes outside of that instance.

Learning from History

I'm sure Jupiter will stick around for the next 2 years, but looking back at our code within that amount of time can feel like a completely different landscape. Bits of code that were worked on by developers long and gone may not be completely understood, but could be crucial to an applications integrity.

https://www.instagram.com/p/BveREmPD9Vb/

Each of these merge request components play a key role in preventing lost knowledge and context of changes to an application. Why was the business logic set up to handle a particular situation this way? Finding the commit and relating it back to the merge request could very well prevent a situation where your application is losing money due to a bug that you wouldn't have thought of without that context.

Bonus: Comments

Feedback is crucial to Instagrammers and developers alike. Being able to learn from others and gain a different perspective is key to not just growing as an individual, but being able to pull the best pieces and wisdom from all parts of your team. Taking and understanding this feedback is crucial to strengthening your application.

How does Element 84 write Merge Requests?

On larger projects, we take some extra effort to help guide our team into writing quality merge requests. Particularly, we use merge request templates to get the job done.

We've tried to break it down into 2 primary topics, an overview of the work and how to test.

## Overview### What is the feature?(Describe what the feature is)### What is the solution?(Describe at a high level how the feature was implemented)### What areas of the site does impact?(Describe what parts of the site are impacted and*if*code touched other areas)## Testing### What's required testing?(Describe the prerequisites for the steps to test)### What are the steps to reproduce?(Describe and list the steps to reproduce - distinguish if instructions are for a developer or QA tester)## Other Notes(Add any additional information that would be useful to the developer or QA tester)

Also available here:https://gist.github.com/colbyfayock/086038bc5e38fd7edf4e73e1602de71c

Since adding this template, we've been able to see a clear upward trend in the quality of our merge requests and subsequently, better historical references to code changes.

How do I add templates?

We're a Gitlab-flavored house for our internal projects, but most Git software should be able to provide the option to add a merge request template. To help get started:

• Gitlab:https://docs.gitlab.com/ee/user/project/description_templates.html#creating-merge-request-templates
• Github:https://help.github.com/en/articles/creating-a-pull-request-template-for-your-repository

Originally published on May 2, 2019 at element84.com