Working In Branches
Project files vary but this guide aims to cover the best practices to create a consistent approach for the wider team working across these files.
Branching is a fantastic way to enable multiple strands of exploration simultaneously with the ability to then merge back into the primary master branch as a reference point. This simple guide is meant to help you understand our approach to this and keeping yourself right.
Any Figma file can be branched, allowing users to work on a file in a non-destructive way. Figma treats each branch as it's own file, so they can be moved or archived in the future if required.
Best advice is that all active work should be in a branch, small change or big, create a branch with the view to get it merged back in as quickly as possible. You can happily juggle many branches at once but try to ensure they don’t linger too long.
Avoid having multiple work strands in a single branch, it makes understanding what’s in the file complex and difficult for people to navigate.
Below are some of the possible use cases for branches:
- Working on a new project based on a master file
- Suggesting a bug fix to a file or component
- Ideating on a piece of work or a component
- Creating a leaner file, such as a prototype, from a larger master file
- Branch the file you want to edit
- Make the changes you would like
- When working with components always update an existing component file, never delete and create new one
- Share for feedback like other files
- Request a review from at least two peers using the branch review features
- Once reviewed, the reviewer should approve the branch
- After receiving two approvals merge the branch back in
- Save 💾 the branch in the version history with notes as a milestone
- IMPORTANT: Make sure the documentation is update inline with any component or pattern changes
Read on for more detailed information on what these steps involve and their purpose
In an ideal world work would be merged back in when it’s live and available to our customers. However, design work can often be completed ahead of time or even feature multiple rounds of refinement. The best advice is to correctly utilise our emoji system inside our files to show where things are at in terms of exploration vs published and try merge content as soon as you believe it to be in a consumable fashion.
Let’s play out an example that might help illustrate this.
Jane Doe is working on a new modal to announce a feature being added to the application. The design has been agreed and all the screens are in place but there’s some back and forth on copy and illustration work that may need tweaked. It’s agreed that this can wait right now as development has been pushed back to next quarter for unrelated reasons.
Rather than leaving the branch open and coming back to it later Jane should tidy up the work and save a version history point and ensure the emoji state still marks it as exploration until published. This work should then be merged before moving onto anything else.
This example shows how to think about when it’s best to merge and branch again later to complete work keeping things nice and tidy for all.
When you branch is in a state you are happy to share with the team either add it to the #team-ux-show-and-share slack channel or the next available UX review.
You can share branches like any other figma file or you can request a review, illustrated below.
If sharing a link on Slack, it helps to provide context on the change with some additional notes as detailed in our Sharing Work guidelines
OK, you’ve decided you’re wanting to merge a branch back in. How do you go about it? Figma’s documentation covers the practical aspects but it’s equally important we follow our peer review process to maintain good standards of quality. The peer review process is relatively simple, no work can be merged back in without having been given the thumbs up by at least two other UX designers.
Within Figma you can request a review from the team, this will launch the above window. From there you can add notes on your work to give context and invite team members to the file.
The review process isn’t there to question design decisions unless they contradict standard component usage and conventions. Rather it’s a means of ensuring people are working consistently.
To ensure consistency we have a checklist available and more information on file reviews in general.
Like all branches, you should request a review from at least two other team members before it is merged into the master.
If you receive a branch to review then read through the context and reply as necessary. If the branch is near completion use the guidelines to check through the file.
Figma allows the reviewer to approve or suggest changes to the branch along with supporting comments. The file creator will require two approvals to merge their changes.
If the changes are to a component, the documentation should also be updated in line with the update.
After receiving the approvals, the file can be merged back into master. Launch the modal and click on the "Merge branch". Figma may prompt you make some updates which you will manually have to work through to avoid conflicts.
Onces the file is merged you can jump back into the master file.
Although Figma adds a marker in the version history. It is always best practice to make sure the branch notes are clear by creating your own save point.