product & design

Design & Git: Guidelines for effective design version control

Chris is... mainly a Product Designer at Novoda, but sometimes people see him opening pull requests on various projects, so nobody is even sure anymore.

For a long time now, the designers at Novoda have been using Abstract as a version control system for our design files. Version control is something that we think every product in development should employ, and we’re excited to finally be able to do something that developers have been doing since forever.

Abstract-1

After using Abstract for a while, we have developed a few guidelines that help our Git workflow which we want to share. Most of these have been borrowed from developers! In this blog post, we’re going to talk about a few best practices, some hints & tips, and we’ve included a super handy Pull Request template.

What is a Pull Request?

First, let’s get some terminology out of the way. Essentially, a Pull Request (PR) is the bundle of edits you have made on the design files, that now have to be reviewed by other members of the team. You are requesting other designers to merge (or pull into the master branch) your edits. It is the final stage of a branch’s life. Abstract doesn’t really use this term, but we refer to our branches that are ready for review as ‘PRs’ anyway.

A good rule of thumb is to write for someone that will be reading after a long time (even yourself).

Name a branch after its purpose.

To give a descriptive name to a branch you’re creating, think about the purpose of the PR that will result from it. Try to complete the sentence ‘The purpose of this PR is to…’. It can be the addition of a feature, a redesign of a certain element, a flaw fix, etc. We write in simple present tense to save some precious characters.

Examples:

Add location type in map
Fix system colour contrast
Redesign widget layout

Commit early and often.

Limit commits to small chunks of related changes. If you were to address two different flaws, they would be two commits. An easy rule of thumb is to commit whenever you save (or press ⌘+S).

Write a small but descriptive commit message.

This is the place to talk about low-level design changes. Talk about what you did, and why you did it. If your commits are small, your titles should be too. If you need to mention more details, add them in the notes section.

Examples:

Add location type question and pop-up window in flow
Add iOS Navigation Bar components
Rename Text Grey to Text Secondary

Create (or to use the correct term; open) small PRs.

PRs should be small enough for a person to be able to go through all the edits and understand their nature without difficulty. Try to keep the reviewing process to less than 5 minutes. We often use Collections to bundle up all the edited screens in one place.

Use a PR template (we’ve written one!)

To add context to your edits, write a description in the Summary of the branch that outlines the essence of the changes. We’ve written a template that we use on all of our PRs, and we’ve added it at the end of this blog post! This PR template tackles two main areas; one, to give a general, high-level idea of what the PR is intended to achieve, and two, to describe the solution that was implemented to achieve the intended purpose in detail, along with any necessary info that someone else might need to know in order to understand the nature of the PR. A good rule of thumb is to write for someone that will be reading after a long time (even yourself).

Finally, ask for a review!

At this point, your design edits should be ready to be reviewed, and the PR description that you wrote should cover all the essential details. Abstract has now added a feature that enables you to assign reviewers to a branch. Wait for their feedback, and make any changes that might be necessary. Lastly, before we merge to the parent branch, we usually upload the updates to Zeplin or Invision.

Fin

Thanks for reading, and we hope that these tips improve your workflow. Don't forget to check out the PR template below! If you have any tips and tricks that you would like to discuss, don’t hesitate to reach out on Twitter!

PR Template (formatted in Markdown)

**What does this PR do?**
Briefly explain the intent of the Pull Request. What value does it 
add to our design files? Is it adding a feature, addressing a flaw, 
reworking a certain element? 

**Solution**
Provide a detailed explanation of the solution. This can contain 
details that you might find relevant for the reviewers to know 
before jumping into reviewing the designs, and even decisions from 
POs and stakeholders.

**How do both mobile platforms compare?**
Explain differences between iOS and Android, if any.

**Paired with**
Mention the designer you have paired with (if the case).

Enjoyed this article? There's more...

We send out a small, valuable newsletter with the best stories, app design & development resources every month.

No spam, no giving your data away, unsubscribe anytime.

About Novoda

We plan, design, and develop the world’s most desirable software products. Our team’s expertise helps brands like Sony, Motorola, Tesco, Channel4, BBC, and News Corp build fully customized Android devices or simply make their mobile experiences the best on the market. Since 2008, our full in-house teams work from London, Liverpool, Berlin, Barcelona, and NYC.

Let’s get in contact