Branching Models and Best Practices for Abstract - Design Version Control

How can you strategically execute on your project system and structure for long-term success?
Here's how, explains projekt202's Peter Vogt

  By  Peter Vogt  Experience Designer projekt202

By Peter Vogt
Experience Designer
projekt202

In the last few years, it has become strongly evident that the need to be both systemic and collaborative in our approach to software design work is crucial. Just as we anchor design work at inception with applied research methodologies, so too should we be rigorous in the handling of composition work and deliverable assets. This has manifested itself in the form of nested symbols in Sketch, components in Figma, platform-level design systems, and more. Now, designers are even applying version control systems like Abstract to empower our workflows.

Fundamentally, we think of design as creative and exploratory. It is. Gustave Flaubert, a French writer with a penchant for aesthetics, famously said to “be regular and orderly in your life, so that you may be violent and original in your work.” I truly believe in this with regards to creative work. I think that version control allows us to re-think the day-to-day process of design in a systematic and rigorous way, while allowing the skills designers have innately to handle the magic. As an added bonus, documentation of design decisions for yourself and your teammates has never been more thorough, thanks to Abstract. It is tough to oversell the value version control can bring to a software team with multiple designers.

I won’t dive into a demo or outline of Abstract or version control for now. I’d like to get into the weeds on approaches designers can take to organizing their branches in Abstract. How do we name branches, how do we name commits, and how often do we do both? These are all questions that are challenging to answer initially as you first begin to wrap your head around version control with design files. Abstract requires you to use it as a middle layer between you and your Sketch files. This alone requires a step outside the comfort zone for most designers. I am sympathetic to the experience of employing version control and promptly thinking, “OK, I’m set up, but how now do I really use this thing long term?” It took one or two tries for me to get it right over the course of ~6 months.

A branching model is a system that your team uses to name, categorize and organize branches in version control. This can help you be judicious in your use of the system so that you may worry less about logistics, leverage versioning to its fullest, and do what you do best: design.

Below, I’d like to unpack some ideas I have around branches and branching models for Abstract, with the hopes of informing teams on how they can think about their work in Abstract. You’ve got a project in Abstract, you have your design source file created for this project, and you want to start building. How can you strategically execute on your project system and structure for long-term success?

It’s important for me to emphasize that this is my personal perception of how we can better work with version control from experience. I’m not here to suggest that the way anyone else uses version control with design is wrong, but that there are - like anything else in the world - many approaches to efficiency. Use what makes you and your team the most powerful.

Best Practice Concepts on Branching

Commit and Merge Early & Often

First, let’s get this out of the way. If you are wondering when to commit work to Abstract, the answer is: all the time. By chunking your work into small pieces, you free yourself up to target past versions of work with precision. That way, it’s easy to take pieces out of your proverbial Jenga tower without the whole thing falling down. If you ever have to remove or restore work, having that work broken into many small commits or (relatively) small branches rather than few large ones is preferable in most instances. I’ll give an example.

Your team decides that the mobile breakpoint versions of your web app’s navigation bar needs refactoring. The IA of the links has been improved after user research; some critical navigation links are getting hidden on tablet-size screens. There are redesign changes to be made to the tablet nav: unhide the hidden links, shrink the text size to accommodate more links, and add drop shadows for more visibility on the links.

... to extract the most value from Abstract, I encourage designers to commit/merge early, often, and with robust annotation to yourself and others.

This may be the approach one would take when first using version control:

-Master Sketch File
            -Branch: tablet nav refactoring

Then, redesign the tablet nav on this branch, making commits along the way somewhat arbitrarily, then merging this branch back into the master Sketch file.

Here is a more modular and efficient approach:

-Master Sketch File
            -Branch: tablet nav refactoring
                        -Commit: Un-hide hidden links
                        -Commit: Decrease link size (14px)
                        -Commit: Add drop-shadow to links

When you are deliberate about your branches, sub-branches and commits (and deliberate about documenting explicitly what changes have been made), you are able to identify the correct Jenga pieces to remove without destroying the tower. Need to go back and remove the drop-shadow? No problem. If all of those three commits were rolled into one big commit, the clarity around pieces of the puzzle is smaller.

Since designers lean in to creativity and exploration, it can be abnormal at first to think of work this way. One may be inclined to just create a branch, do a bunch of free-form work creating all kinds of mockups, while committing the work along the way. This is still very much better than no version control! But to extract the most value from Abstract, I encourage designers to commit/merge early, often, and with robust annotation to yourself and others.

No project too small for a branch or sub-branch  

This is an extension of the above point regarding committing and merging often. Even if you’re doing release cycle branches with sub-branches per sprint, you can always create sub-sub-branches. Adding just one artboard to your project? No problem. “Adds remaining Checkout artboard” is a perfectly fine branch title.

Be vigorous in your documentation on merges

The more you document in your merges, the better. It’s optional to add any annotation at all in Abstract for merging, but it behooves you and your team to take advantage of this feature. Here’s an example of a well-documented merge:

“Branch: Password management exploration

Merge description: This merge contains all of the exploratory work for password management in Sprint 2.”

Additionally, Abstract provides a “Summary” input field on the Overview tab of each branch. You can use this (with markdown if you like) to provide context on your work on a branch even further.

Being descriptive in your commit and merge documentation helps you and your team remember why things were done, and when. How much of your project is historically documented? What percentage of knowledge in your company is tribal in nature, and only gets shaken out after countless meetings and emails? It would strike me as more optimal to have all of these historical design decisions and answers to internal questions documented clearly alongside the design work, all in one place. With proper documentation, Abstract helps you minimize the gaps left in the wake of collaborative design work over time, and acts as a soundboard for the contextual history of past work for your team members.

Remember - All is never lost

The beauty of version control is the ability to jump back in time to when your design was different. Maybe you changed the location of a button from the bottom right of all of your artboards for a workflow to the top right. After some review, it turns out that this actually was detrimental to discoverability and ease-of-use.

Rather than delete and copy-paste all the buttons back in their original place, you simply need to head back to a version of your designs in the past that contained the aforementioned buttons in the bottom right of your artboards. Create a new branch off this old version, re-name it something like “button location fix,” and merge it back into master.

If you have changes that need to be shored up outside of the buttons, Abstract will generate side-by-side diffs for you to approve which conflicted versions you want to keep or discard when you merge the “button location fix” branch.

Another option to “restore time” is to open your old commit or branch “Untracked” in Sketch through Abstract, copying the required changes, and applying them to a fresh branch off master.

Branching Models

Branching at the Sprint Level

One suggestion is to branch at the sprint level. This assumes that you are working in an agile team. There are advantages and disadvantages to this branching model.

The main advantage is, if you serve primarily as an in-sprint designer supporting a development team, you’re likely working in this fashion already. Most in-sprint designers will be one or two+ sprints ahead of their developers. If you’re taking UX stories from a backlog to work on in concordance with the development roadmap in front of you, a sprint-based branching model for Abstract makes sense.

Your branch model would look as follows:

-Master Sketch File
            -Branch: Sprint 1
            -Branch: Sprint 2

And so forth. This seems practical, but may not be enough organization. At some point, you may want to have an additional top layer of categorization. If your team ships things in release cycles or (sometimes arbitrary) time periods, you could organize sprints as sub-branches within a cycle. So:

-Master Sketch File
            -Branch: Cycle 1
                        -Sub-branch: Sprint 1
                        -Sub-branch: Sprint 2

            -Branch: Cycle 2
                        -Sub-branch: Sprint 1
                        -Sub-branch: Sprint 2

And so on, for however many release cycles your team does in a year. I have seen organizations that put out four releases a year - one release per quarter. Were this the case, that additional layer of categorization might not help much.

Branching by Feature

Another branching model that is practical would be branching by feature. With this, you’re treating your branches like epics. This would be advantageous in that your version history wouldn’t be tied to sprints, potentially making it easier to search down documentation or changes in history that happened at the feature level rather than the sprint level. So, you’d be looking at a branch system like this:

-Master Sketch File
            -Branch: Checkout Flow
                        -Sub-branch: Checkout pages
                        -Sub-branch: Checkout messaging
                        -Sub-branch: Payment method management
            -Branch: User Profile
                        -Sub-branch: Password management
                        -Sub-branch: Avatars
                        -Sub-branch: Location details
            -Branch: Navigation
                        -Sub-branch: Desktop navigation
                        -Sub-branch: Tablet navigation
                        -Sub-branch: Mobile navigation

Your personal use of Abstract will vary highly based on team size and what type of work you’re doing, but I do prefer this branching model. I think it emulates the process of user story epics well, but makes concepts easy to revisit. My gut instinct tells me that this model more accurately represents a designer’s way of thinking. Many of us probably set up our Sketch pages in source files by feature. If we want to go back and update the password management screens, we look for the password management screens, not necessarily the work that was done in Sprint 4.5 last year.

Here’s another suggestion provided to me by Alden Spence of Abstract that their team has been experimenting with. It involves a little bit more thought to process immediately, but he reports that pushing changes over time has a nice waterfall effect with this branching model:

-Master Sketch File
            -Branch: Release 75
                        -Sub-branch: 75-Feature1
                        -Sub-branch: 75-Feature2
            -Branch: Release 76
                        -Sub-branch: 76-Feature1
                        -Sub-branch: 76-Feature2

Here’s the important part of this model: branch “Release 76” is created from Release 75’s last complete sub-branch (Feature 2 in this case). This creates a waterfall effect of cascading changes through your branch model.

Branching and Sub-branching by Contributor

Branching by designer in a team may be one way to track your team’s work. Personally, I think this may not be the most future-proof way to manage your version control, but it *is* a concept that could possibly work for your team.

In this scenario, maybe you break up Master files by sprint or release cycle, and then organize design work by the designer. This would give you a slightly higher level of control over the version history over a long period of time. So the Project for “Q1 2018” would contain all the work done by one design team in Q1 2018, organized with branches for each designer and sub-branches for each individual project in that quarter.

In this scenario, your branches could look like:

-Master Sketch File (Project - Q1 2018)
            -Branch: Peter
                        -Sub-branch: Password management
                        -Sub-branch: User profile management
                        -Sub-branch: Marketing page
            -Branch: Emily
                        -Sub-branch: File uploads
                        -Sub-branch: Admin panel
                        -Sub-branch: Product catalog screens
            -Branch: Lindsey
                        -Sub-branch: File storage workflow
                        -Sub-branch: Documentation pages
                        -Sub-branch: Color system exploration

This way, you can keep track of each other’s work per quarter and per person. It would be important to include some sort of description of the branch’s content in the name as well, so that your project’s merge history wouldn’t simply be “Merged: Peter, Merged: Emily”, etc. Again, I can’t quite see a fit for this model for me, but I could see it being practical for a small team at a startup.

Summary

A well-considered branching model and approach to breaking up work in Abstract is the difference between entry-level and advanced level use. With deliberate precision on branching, committing and merging, you’ll make the most of version control and take your team’s communication skills to the next level.


projekt202 is the leader in experience-driven software strategy, design and development. We have a unique and established methodology for understanding people in context — we reveal unmet needs — which drives everything we do. This leads to a crisp, clear understanding of the customer, which shapes the design and development of new solutions and experiences. We have the expertise, teams, skills and scale to deliver sophisticated software solutions that improve any and all touchpoints across the user journey.

projekt202 has spent over 15 years bringing to life and to market compelling experiences through our Experience Strategy & InsightUser ExperienceSoftware DevelopmentMarketing & Analytics, and Program Management practices. Our talented team has delivered emotionally-rich and intuitive solutions for global brands and clients such as 7-Eleven, Allstate, Canon, Capital One, Dell, McKesson, Mercedes-Benz Financial Services, Neiman Marcus, Samsung Electronics, Subway and The Container Store, among many others.

projekt202 has offices in AustinChicagoDallas and Seattle.

CONTACT US TODAY TO DISCUSS HOW THE PROJEKT202 TEAM CAN DELIVER RESULTS FOR YOU AND YOUR TEAM.  

FOLLOW US ON LINKEDIN AND TWITTER FOR THE LATEST PROJEKT202 NEWS.