1: When should I commit — you’re here 📍
2: Writing commit titles and descriptions
Before you commit
Once you’ve created a project and opened a branch where you can work on the design files, commits are how you save the history of that work to Abstract. The basic flow of work in Abstract is Branch → Commit → Merge, though your branch is likely to have several commits before it is ready to be merged.
So what is committing, really? When you boil it down to a core principle, committing changes to a branch in Abstract is how you identify and record the changes to your design files.
How are saving and committing different?
When you click save while working in a Sketch or Adobe XD file, the changes you made on that single file are stored on your computer. Those changes are there for you the next time you open that file in that branch, but they won’t be visible to the rest of your team. If you save without committing, your Sketch and Adobe XD files are not backed up in Abstract. You must commit changes for your team to see them.
Commits in Abstract are like a super-save because they have extra context: including a visual overview of the changes made to one or more files in that branch, and a written message about what changed. Those commits are threaded together to create the timeline of work that has happened in a branch. When you commit, the visual previews and your written commit descriptions of those changes are stored in Abstract and made available to everyone on your team.
When should I commit?
Many of you have asked us, “How often should I be committing?” While the answer may vary from person to person, let’s outline some essential guidelines.
Your commit history on a branch should tell a story about the feature or functionality that you have added by doing that work. You probably save your file pretty frequently to ensure that you don’t lose work, but committing should be done less frequently and more intentionally than you would click save.
The main rule we suggest you follow is to commit when you have completed a unit of work.
Commit when you’ve completed a unit of work
Within the domain of version control systems, individuals and teams have had success by using this method to decide when and how often to make commits. However, to commit based on a unit of work, we have to define what is a “unit of work.”
What is a unit of work?
- Progress made toward a feature or release
Whether you’re adding or removing an entire feature; fixing, updating, or changing how a feature appears or behaves; or exploring new ideas for a feature – any of this can be considered a unit of work if the end result is a measurable change from how the designs started out.
The power of committing is in tracking the journey of your design changes over time. By keeping the story of the design in mind, you will be able to make meaningful commits about what unit of work was completed. You don’t have to complete the entire feature in order to commit since the design process often takes days, weeks, or months – but your commits should contribute to the ongoing story about that feature.
Examples of units of work:
- Added a chatbot widget
- Updated the chatbot to include ability to chat with a representative
- Inserted copy for basic chatbot new conversation sequence
- Adjusted chatbot spacing to fit design system specifications
- Simplified chatbot by reducing number of visible icons
Asking yourself, “What did I change and why?” is a useful way to think about commits. If you can answer this question with something concrete, you have completed a unit of work and are ready to commit.
Other types of commits
There are exceptions to any rule, and committing is an area that can be quite flexible. You’ll often see smaller, “cleanup” type commits at the end of a branch’s life cycle that don’t necessarily follow the convention described above. It’s okay to sprinkle in other commits when you need to fix a problem, stash an idea, clean up a file, or prepare your branch for merging or archiving.
- Add: New chatbot file
- Stash: Exploration of chatbot v2
- Cleanup: Removed chatbot v2
- Polish: Finalizing pixels
- Copy: Fixed typos, errors, and incorrect messaging
If you click commit to start writing a commit and then change your mind, Abstract will save your title and description when you click cancel. You can use this function to reduce the number of cleanup commits by starting a running list of the cleanup changes you've made until you know you're finished and ready to save the commit.
In the next section, we’ll outline more examples of good commit titles and talk about how to use commit descriptions.