Best practices when using branches

Naming your branches

Once you've decided to use branching, one thing to consider is naming your branches to clearly communicate what they contain or address. A common practice in development where branching is used with code repositories is to prefix the branch name with something to quickly identify it. This could be a ticket number, type of work, emoji status, or similar:

UX-5141: Redesign login screen
🔥 Layout fix for payment info
[contrib] - Propose a new design for tabs

If you don’t have a current naming convention for design work, one thing that I like to recommend is talking with your development partners to see what type of conventions they use. If there's an opportunity to align and use the same conventions, it can help streamline communication across the entire process!

Requesting a review on a branch

If you're an editor in the organization, you can create a branch on any file that you have view or edit access to. If you're a viewer on the file—say a design system asset library in another team—you will not be able to merge the branch directly and will need to request a review from an editor of the file. There are two ways to get feedback from the editors of the file, either via comments as you're working in a branch or using the description field when you request a review.

If you're looking for feedback while making edits in your branch, we recommend tagging an editor in a comment as you're working. This will send them a notification, and they can switch to your branch to view in-progress changes, leaving additional comments as the work is being completed.

Tagging an editor in a comment while working in a branch

Once you have finished your exploration and are ready to have it merged, you can easily request a review from the editor(s) of the main file. The review window will automatically recommend some editors of the main file, and you can specify others to include in the review as well.

When requesting a review you’ll want to give as much context as possible. Be sure to fill out the description field with the details of your proposal or issue being solved to help the editors of the file know what they are reviewing in your contribution. This is similar to how a PR request is made in the engineering process and a great opportunity for process alignment!

Adding reviewers to a merge request

Merging branches

When you want to apply your changes to the main file, you can merge the branch. If you're an editor on the main file, you can initiate the merge to review any changes from main in the branch and resolve any conflicts that may appear.

Editors of a main file can merge a branch of it without a review

After a branch has been merged into the main file, it's automatically archived along with all comments made within it and can no longer be restored. If you need to undo a merge, you can restore a previous version of the file from the version history.

Restoring a file to the point before a branch was merged

Manually archiving branches

When you have designs in a branch that you’ve decided not to move forward with right now, you may want to archive it in case you or your team want to come back to it at a later time. Archived branches will continue to be associated with the main file, and links shared from a branch will continue to work even when archived. If your branches have been archived without being merged into the main one, they can be viewed or restored at any time, making it easy to recover them if you need to revisit an idea.

This saves you from having multiple branches in flux that may be outdate, which causes confusion for others accessing the file. Your archived history of branches will also remain until you manually remove any branches that are no longer needed.