Your First Merge Request

If you’ve been assigned an issue but you have only worked on personal projects, odds are you haven’t worked with branching and merge requests at scale. This page should help you make your first merge request without having to ask too many questions. It’ll also cover some more complex topics like rebasing.

Before you start a branch or do a rebase, you should always git pull to make sure you are up-to-date with the main repo and currently on the origin branch.

What is branching?

The concept of branching is fairly simple. Each repo has an origin (master, develop, prime, main etc.) and branches are forked off this main repo.

When you have an issue assigned to you, the first thing you need to do is make a branch. When you make a branch, it should reference the parent issue that you are writing code for, so that it’s easy to refer to.

git checkout -b <issue_number>-name-of-your-branch

This will checkout onto a different branch and the -b switch tells git to create a new branch with the name you supplied. Using without the switch means the branch already exists (and if it doesn’t and you try to switch to a non-existent branch you’ll get an error).

For example, if we are creating a simple new feature, and the issue card is #722, then we’d do:

git checkout -b 722-a-simple-new-feature

Now you can make your changes!

When you’re ready to commit, follow these commands:

git add --patch
git commit
git push -u origin <issue_number>-name-of-your-branch

Note: Adding with the --patch flag lets you atomically select what you will be adding to the commit.

So as per our example it would be:

git add --patch
git commit
git push -u origin 722-a-simple-new-feature

In your commit message, include a one-line, brief description of the changes you just made. This one-liner should be succinct and be a very high-level overview of the change you made.

Don’t

When writing your commit message, avoid:

• passive voice
• ambiguity
• over explaining

As an example:

This issue addresses the problem where you couldn't reel in the lines used for fishing as a deckhand even if you could cast a line and get a bite. It fixes it by ensuring the condition of one bite is met before the deckhand can reel in the line.

Do

• use active voice
• keep it simple
• what for, not what

A better version of the previous example:

Fixes deckhands being unable to reel in their line even if they had a bite

This makes your commits easy to grok (understand) and removes unnecessary verbiage.

Fixes deckhands being unable to reel in their line even if they had a bite

Creating a merge request

The first commit to remote will prompt you to create a merge request. You should click on the link supplied, assign yourself, add an approver (usually your teammate(s)) and add any other commentary or important information about the commit.

Sometimes your work may (in)directly impact other teams. Most of the time this will be captured by the CODEOWNERS file, but you may need to manually add people for review if you know that somebody outside that team is a SME (subject matter expert).

Commentary

If you are making a significant MR (more than 1-3 weight), it can be helpful to add commentary to your code changes. This provides the reviewer better context and understanding of your frame of reference.

When viewing the changes to the code, you can click on a line to add a comment, or select multiple lines to comment on a block of code. In these comment blocks you can add important information such as:

• why you chose a specific implementation over another (for example, readability)
• why you had to make changes to linting configuration, etc. (for example, syntax change)
• why a change was needed if it’s seemingly irrelevant (for example, broken tests)

What if I need to make changes after I’ve pushed?

If you need to make changes or rewrite some code after your changes have been reviewed, make them! Then, if it is a new commit entirely:

git add --patch
git commit

If the error was typographical or minor you can add to the previous commit with the --amend flag:

git add --patch
git commit --amend

For more information on commit amendments, check out this article by Atlassian.

Once you’ve made your amendments, you can now do a force push (this simply means to override the previous push). If you do not use the -f switch, your push will fail, due to the commit already existing on the remote:

git push -f

My code is fine but my pipeline is failing

If you’ve confirmed your pipeline isn’t failing because of spot instance issues and you and your reviewer are sure the code is a-ok, you probably need to rebase.

Rebasing is much like the word sounds. It takes the commits you’ve made and rebases them off the most up-to-date version of the origin repo.

Conceptually, you remove all the changes you made, update the origin repo, and then reapply the changes you made.

Note: When rebasing a large MR or when your feature branch has fallen a long way behind the origin branch there is a greater chance for Conflicts. There can sometimes be tricky to get through, and it can be easier to revert a rebase and start again then complete it with errors. For this reason you can “backup” your branch or create another branch before rebasing if you are concerned

To “backup” your branch, perform the following:

git checkout <issue_number>-name-of-your-branch
git checkout -b <issue_number>-backup

To rebase, perform the following:

git checkout <origin>
git pull
git checkout <issue_number>-name-of-your-branch
git rebase <origin>
git push -f

Note: <origin> for most intelliHR repo’s is main but it might be develop or master, depending where you are working.

To learn more about rebasing in depth, take a look at this article by Atlassian.

Final words

If you get stuck with anything, don’t hesitate to ask! If it’s not documented, add it to the handbook!