Prepare your branch for merging

1: Before you branch
2: Working in a branch
3: Ready to merge — you’re here 📍

As we’ve been saying all along, it’s important to be thinking about merging before you even open a new branch. If you’re planning and being thoughtful ahead of time, things are more straightforward when it comes time to merge. Here are some essential tips on merging, including what you should think about, why merge order matters, and what to do to avoid conflicts.

  • Try to think about the end result of merging throughout your time working in your branch. Remind yourself what outcome you are intending and what your branch represents.
  • Try to stay focused; if you need to update something that you know will impact others, you should instead open a new branch just for that one item.

Why merge order matters

Whether you have several parallel branches under the main branch, or a parent branch with many child branches, the order in which you merge branches does have an impact. Understanding the impact of merge order minimizes conflicts and reduces duplicated work.

For example, let’s say that you are given a project to design a new feature for your product. First, create a parent branch for that feature. This is a large effort, so you want to break this down into smaller pieces. Create child branches for each separate item which, when put together, make up your new feature.

You and your teammates work in those child branches until each small piece of the whole feature is done, and then you start merging those branches. Here’s where merge order comes in. The first child branch you merge back into the parent updates the parent branch, and now you have to bring those updates into the other child branches before you can move on with them. If the child branch you merged has a lot of changes, you may notice many conflicts that you need to resolve in your other child branches. If you merged small changes back into the parent branch, there will be smaller changes to go back and fix on the other child branches when you bring in the updates. 

With this in mind, you may want to merge smaller items back to the parent branch more frequently so you can handle conflicts on the other child branches easily. If you do that, the last branch you merge might have many changes, but you only need to resolve conflicts for that one branch.

How to avoid conflicts when merging

Regardless of how carefully you work, conflicts happen, even in the world of engineering. 

  • Don’t open or change a file unless you need to because the odds of running into conflicts at merge are higher if you’ve impacted too many files, especially ones others might be working on.
  • Try not to delete anything (artboards, pages, files) on the parent branch until child branches are merged.
  • When updating your branch from the main branch, only choose your artboard when you know you made a change on that artboard. Embrace it as a moment of reflection on the work done.
  • Be discerning when updating from the main branch. You are responsible for the merge, so if you pull in work you didn't do, you are now accountable for that work.