Version control is a new (and powerful) capability for most designers. With the recent launch of Abstract, many designers are gaining the benefits of version control for the first time, and I hope will start to weave it into their daily rhythm. While the deign works is still in the early easy to use version control, there are many existing conventions that we can adopt from developers.
Writing good commit messages is one of the most valuable practices we should learn from. A quick search for “git commit message conventions” returns a wealth of articles, demonstrating how much thought the development community has put into the subject. We can distill and modify their ideas to meet our needs when working with design files. So, on that front, I have a few recommendations for anyone using Abstract or other version control system for their creative work.
Make the Most of Your Commit
The Title
Abstract provides a Title field, which is analogous to an email subject line. So keep it short! Limiting it to 70 characters makes it easy to skim a list of commits to understand what changed and when. If you’ve integrated Abstract with Slack, it will make each auto-post that much more useful, reducing questions from teammates. Each title should be useful to the reader, including your future self. So make sure to write concise, useful messages in a consistent style every time you commit. Resist the temptation to use it as a place for commentary, venting or jokes.
A Consistent Voice
For the message itself, I personally like active voice in the past tense – “fixed alignment of left column” or “removed secondary call to action which confused users”, but your team should select a style that works well for you. The key is settling on one, making it easy to skim the list, while reinforcing good writing practices among the team.
Connecting the Dots
If you use a ticketing system, it’s useful to include the appropriate ticket number in your commit message when applicable. This makes it easier to search for a specific change down the road. In time, I expect we’ll see integrations between ticketing systems like Jira and design version control apps like Abstract, providing bi-directional links between the two.
Examples
fixed alignment of left column. Jira #12345removed secondary call to action which confused users. Fixes #789Introduced new pagination component to better handle 100+ results
Provide Additional Context in the Description
It’s useful to include the “why” behind the change in the description, especially for key commits. This provides insight in the future and allows you to keep the title clean and concise.
A Note on Large Commit Messages
If it’s hard to describe all of the changes, you likely need to commit your designs more often. This makes it easier to track work over time and it adds a layer of protection should some unforeseen event corrupt your file or system. This has the added benefit of making it easier to branch your designs from any point in time, if you want to try a different design direction.
Wrapping Up
This is a dynamic time to be a designer. We have so many new tools than we did just a few years ago, making our lives easier and extending our capabilities. Version control in particular is huge. Taking a bit of time now to set good practices (and continuously enforce them) will pay huge dividends over time.