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
Get more content straight your inbox!
Originally published on May 2, 2019 at element84.com
Top comments (6)
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
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!
thats a great idea! especially for people new to a project
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.
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
thanks. that was too easy ;-)
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