Committing — Part 2

1: When should I commit

2: Writing commit titles and descriptions — you’re here 📍

Writing commit titles and descriptions

There are two pieces to any commit in Abstract: the title (required) and the description (optional). Let’s outline some good practices for naming and describing your commits in order to tell a story about the work being done.

Give your commit a title

When you’re viewing the commit history on master or any branch in Abstract, the commit title is what immediately stands out. That’s why it’s a required field and it’s also why writing clear titles for your commits will help you keep track of design work.

We recommend that you give your commits a title that will help you understand the story of how that work was progressing – even if you’re looking at it several weeks or months later. Think to yourself: “If my colleague were only to read this commit, would they get it?” When your whole team agrees to a naming convention for commit titles, you’ll also be able to scan through other people’s work and understand at a glance what they were working on.

Here are some handy commit prefixes that you can use to start off your commits.

  • Fix (fixing an issue with the file)
  • Copy (changes to content)
  • Style/Polish (formatting, spacing, sizing, colors, etc.; no major structural changes)
  • Chore/Cleanup (cleaning up the file, other minor tasks, etc.; no major design changes)

Use the commit description

Every commit has an area for you to add a description, and while it is optional, we highly suggest you use it. The commit description will be displayed when you click on any commit in the commit history view, so this is your opportunity provide any missing context that the commit title didn’t convey, to communicate a story around your work, to explain how and why decisions were made, to show when and where consensus was reached, and to list who else provided input.

Some things to consider when writing a commit description are:

  • What has changed?
  • What problems are you solving with these design changes?
  • What decisions did you make and why?
  • What should reviewers look for or test out?

Tip: Commit descriptions also support markdown, which makes it easier to organize your thoughts. Here are some ways to use markdown in your commit descriptions:

- Use bullet points to outline clear and concise notes
- @ mention people who need to be informed or review your work
- Add a link to a related document