Set up a new branch

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

Before you branch

Whether you're brand new to Abstract (in which case, welcome! 👋) or have been using it for some time, you may have questions about how to branch most effectively. Abstract, which is based on Git, leverages a tool that may be unfamiliar to some designers: branches. Branches allow designers to work safely in parallel on the same design files, without the worry of overwriting each other’s work. 

We've collected a list of tips, tricks, and best practices from experts to help you branch with more intention and less stress.

What to know before you branch

Designers often start work assignments by documenting questions, ideas, observations, and assumptions before jumping into Sketch. With Abstract in the mix, it’s no different: Think of branching as the time to set yourself up for success with some design thinking. Before you create a branch, consider four proactive questions: 

  • What’s my intention with this design?
  • What’s the current state of the design?
  • How much effort does this assignment require?
  • What should I name my branch, with all this️ in mind?

Determine intention

With any new design, you need to know the context, intent, and desired outcomes of the work you’re embarking on. Clarifying these things in advance goes a long way toward maintaining scope, working efficiently, and making forward progress. 

Here are some questions you can ask yourself to establish intent:

  • When I merge these changes, what do I want the result of my contribution to be?
  • Is this effort part of a ticket or task? Or, is it more of an open-ended exploration?

Depending on your intention, you may choose to create a parent branch or a child branch.

What’s the difference between a parent branch and a child branch?

Parent branches start out as a direct replica of the main branch. Make a parent branch when you want to start from the source of truth (i.e. the main branch) to begin designing.

Child branches, on the other hand, start out as a direct replica of their parent branch. This means child branches can include changes that are part of the parent branch, but aren’t yet merged into the main branch (and, therefore, likely haven’t been approved by your team).

Here’s one way of how we think about the difference: 

  • Parent branch = Rough ideas for improving a feature of the product.
  • Child branch = An exploration of a new aspect of the above feature.

Identify current state

When someone wanders into your branch, you want to let them know right away the type of work you’re undertaking.

Internally at Abstract, we use emojis we use to quickly communicate a branch’s current state - feel free to copy us!

  • 🏝 Explorations: not on the roadmap
  • 🔷 On roadmap: in Jira or productboard
  • 🔮 In progress/future work: stable enough for others to build upon
  • 💅 Polish: cleanup; no significant changes
  • 🔥 Quick-fix: fixing a bug
  • ️ Copy edits
  • 🌺 Ready for development
  • 🚧 In development
  • ⏸ Paused

Tip: You can rename your branch to reflect updates to your branch state at any time.

Calculate effort

At the outset, determine how much effort your branch will involve. Identifying this assists later on when you are facing reviews, approvals, merges, and the general workflow of a branch. Generally speaking, these are the two types of initiatives:

  • Exploration effort. Unlike clearly scoped work, this is open-ended and variable.
  • Long-term effort. This is your typical feature design work. (Think: “I’ll be working on a large feature for a while.”)
  • Short-term fix. This is a minor item that you can improve and likely takes only a few minutes or up to a day or two. (Think: “My team needs to benefit from this new icon I created so I’ll want to merge it as soon as I can.”)

The short term fix is a unique situation in which you have the opportunity to do something kind and helpful to many people at a minimal cost. For example, if you see something in a design that’s broken, you have two choices: fix it in your branch to make it better just for yourself, or open the file in a new branch, make that discrete change, and merge it back to the main branch to improve everyone’s experience.

Tip: It's okay to have branches for everything — don't be afraid of creating branches! Whether it's small fixes, visual polish, file cleanup, or distant future explorations, anything goes. The size of the impact doesn’t matter. Also, don’t be afraid to branch off of someone else’s branch.

Name your branch

Like a writer facing a blank page, naming your branch can be intimidating. 

Let’s make it simple: The name of your branch reflects that you’ll work on next. It definitively states to you and everyone else, “This is the scope of this assignment and no more.” When you start a branch with this level of clarity, you kickstart your creative process in three ways:

  • Scope: You clear away distractions and guard against the dreaded “scope creep”.
  • Focus: You commit yourself to a specific deliverable (e.g. Gift card checkout flow).
  • Structure: You make it easier to find related work months or years later. Use Cmd + K to launch Quick Jump and find all branches related to “Password reset,” for example. 

Tip: Want to explore some new ideas unrelated to assigned design work? Check out our recommendations for setting up your branch for exploratory work.

As you know, Abstract is based on Git, a version control system which engineers have been honing for the last 15 years. We can take a leaf out of their book and learn from them how best to branch.

Engineers lead with keywords that help identify the type of work. They call this practice “semantic git,” and they use it for commit names. At Abstract, we've extended this idea to branch names as well. Here are some ideas to get you started:

  • Feat (designing a new feature)
  • Update (updating an existing feature)
  • Explore (playing around with a new design idea)
  • Fix (fixing an issue with the file)
  • Copy (changes to content)
  • Style/Polish (formatting, spacing, sizing, colors, etc.; no major structural changes)
  • Chore/Cleanup (cleaning up the file, other minor tasks, etc.; no major design changes)

How to write a branch summary

It can feel like an impossible task to include every bit of vital information in a branch name with a 56 character limit. That’s where a branch summary comes in handy. Write a branch summary to give richer context to your future self and your team.

Feel free to copy our branch summary template below (the Markdown and emojis work great!):

**JIRA** 🔷[STEM-624](
- 💡[Idea Doc](
- 🔍[Research Doc](
- 📜[Project Charter](
- ✏️[Design Doc](
- 💬[Conversation](
**Context:** On the product page, we need to update the image layout.
**Problem:** As a user, I can't view all the images of the available selections.
- User will be able to view images of all available sections.
- Users will spend less time searching for the sections they need.
- Assumption 1
- Assumption 2
**Engineering Insight**:
- We are able to preload images.
**Proposed Solution:**
- Add carousel of preloaded images
- Please verify that this fits within our current design system patterns.


Now, the only thing left is to start editing your files in your branch!

Part 2: Working in a branch →