DEV Community

Cover image for Write Merge Requests Like You’re Posting to Instagram
Colby Fayock
Colby Fayock

Posted on • Updated on • Originally published at element84.com

Write Merge Requests Like You’re 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.

Gandalf - You shall not merge this code!

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.

NASA Instagram Jupiter
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.

That's no moon. Right, it's Jupiter

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.

Thanos Meme: What did it break? Everything
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)
Enter fullscreen mode Exit fullscreen mode

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:

Get more content straight your inbox!

Originally published on May 2, 2019 at element84.com

Top comments (6)

Collapse
 
dangoslen profile image
Dan Goslen

This is great! Our team did something very similar and it has helped us a ton.

One additional thing we did was add links to other documents where we detail

  • what to look for when reviewing code
  • our definition of done
  • a specific list of gotchas we have encountered

The intent isn't that every PR must comb through all of those documents, but we all know where they are and they can guide us if we face a problem or a disagreement.

Thanks for sharing!

Collapse
 
colbyfayock profile image
Colby Fayock

thats a great idea! especially for people new to a project

Collapse
 
erikpischel profile image
Erik Pischel

Given a commit, how do you find the corresponding merge request in gitlab? Say after a year or so.

I document the how-to-test part in the ticket not the MR.

Collapse
 
colbyfayock profile image
Colby Fayock

If you keep up with tagging the commit with the ticket number, for instance, we do [JIRA-###], you can trace it back and look it up in the Gitlab search.

the thinking is the ticket is more about the problem, where the MR is more about the solution

Collapse
 
erikpischel profile image
Erik Pischel

thanks. that was too easy ;-)

Collapse
 
colbyfayock profile image
Colby Fayock

also, we use JIRA & Gitlab integration, where the MR is linked on the ticket, so it's another way to easily trace back by clicking through from the ticket