Tag: Documentation

5 March 2020 by Phillip Johnston • Last updated 14 December 2023

Preparing quality commits in a source control system is an underrated skill. Commit messages help explain the context for set of changes. We can’t always find an explanation or context for why code was changed by looking at the code. We must keep a detailed project history in some other way, and the commit tree is one of the best places. This history is invaluable when debugging future problems or trying to understand why a previous change was made.

Additionally, how we structure our commits matters. With commits that are too large, reviewers will have trouble processing all of the information. Future debugging efforts are also hindered, because developers cannot pinpoint exactly where an error was introduced when large commits are the norm. We want to build a project history that is truly a future resource for future developers.

The following commit guidelines are used on Embedded Artistry open source software projects to provide a consistent organization style. If your commits and messages are not of sufficient quality, you may be asked to amend them before a pull request is accepted.

In general, these guidelines will serve you well no matter your organization. For other takes on writing quality commit messages, see the Further Reading section below.

Table of Contents:

1. Prefer Atomic Commits
   1. Splitting Commits
   2. Whitespace and Formatting Cleanup
2. Commit Message Guidelines
   1. The Subject
   2. The Message Body
   3. Reference Issue Numbers
   4. On Cherry-Picked Commits
3. Revise Your Commits Before Submitting a PR
4. Further Reading

Prefer Atomic Commits

In general, the smaller the commit, the better. We prefer atomic commits, which apply a distinct and related set of changes in a single action.

What does this mean in practical terms?

1. All changes in a commit should be related.
   1. Don’t combine changes that address different problems into a single commit.
2. All changes in a commit should address a single aspect of a problem or change.
   1. Don’t be afraid to break up a new feature, bug fix, or refactoring effort into multiple distinct changes.
   2. This will help you keep track of what works and what doesn’t: if there’s a problem, you can always revert back to the last known good state. If you wait too long between commits, you may lose a lot of work or spend too long finding the source of the problem.
3. Prefer small commits to large commits.
   1. This helps reviewers by allowing them to focus on a small set of related changes.
   2. This helps future debugging efforts by increasing the probability that a git bisect operation will quickly identify the source of the problem.

Splitting Commits

Sometimes, we accidentally commit distinct sets of changes together. Or we might mess up a rebase effort, accidentally squashing two unrelated commits.

To undo this problem, review our process on splitting up git commits in the middle of a branch.

Whitespace and Formatting Cleanup

Don’t mix code changes with whitespace or formatting changes! If you are fixing code formatting, include those changes separately from your code changes. If your request is unreadable due to whitespace changes, it will be rejected.

Many of our projects enforce automated code formatting using clang-format. Formatting is enforced by the Jenkins build server which runs continuous integration for this project. Your Pull Request cannot be accepted if the formatting check fails. If your changes are rejected by the server, please include the auto-format updates in a separate commit.

You can auto-format your code to match the style guidelines by issuing the following command:

make format

If you don’t have clang-format installed, we can apply the format changes for you.

Commit Message Guidelines

Below is a visual representation of the Embedded Artistry git commit message format:

50-char-ish"subject" which summarizes the change

After the first line, include additional explanatory text. Include
one blank line in between the summary and the body. Various tools
like git log, git shortlog, and git rebase get confused if the two
sections run together.

You can also include bullet points:
* A
* B
* C

Reference issues at the bottom, like this:

Fixes #102
Relates to #100, #8

The Subject

Treat the first line of a commit message like an email subject line.

We recommend a maximum length of 50 characters because it works best with git’s command line tools.

We also recommend using the imperative mood for subjects. This might be what you think of as “commanding” or “instructing”. Examples include:

• Refactor subsystem X
• Implement feature Y
• Remove deprecated methods
• Update version to 1.2.3

Another way to look at it is to have your subject line complete the following sentence:

If applied, this commit will [subject line here].

We don’t worry about manual line breaks in our commit message bodies. Text wrapping works well in modern tools.

The Message Body

Please separate the body from the subject with a blank line.

Most importantly, the commit message body should be used to explain what you are doing and why you did it that way, rather than how you did it. The code itself serves to explain the how. Focus on side effects, compatibility changes, or other consequences that are not immediately obvious from reviewing the code. Also include any important factors that helped you arrive at your particular approach.

Not all commit messages require both a subject and a body. You can include only a subject if it is sufficient for a given commit.

Reference Issue Numbers

When working with GitHub projects, reference relevant issue numbers in your commit message body.

You can have a commit automatically close an issue when it is merged to master by saying something like the following in your message body:

Fixes #123
Fixes: #123
Resolves: #123

You can also reference issues in other repositories by adding a prefix for organization/repository:

Fixes octo-org/octo-repo#100

If other issues or PRs are related to this commit, but it doesn’t address the problem, you can include the issue/PR number without using a keyword like “fixes” or “resolves”. This will link the commit and the issue in GitHub’s web interface.

On Cherry-Picked Commits

Sometimes, we cherry-pick changes from one branch to another. We recommend using the -x flag with git cherry-pick, which references the original commit ID.

For more information, see Git Cherry-pick Recommendations.

Revise Your Commits Before Submitting a PR

While you’re working on a problem on your own branch, don’t worry about getting these commit details perfect. Instead, clean up your branch before you submit a PR. You can perform a git rebase to squash commits, amend commit messages, and more.

We often use a visual tool, such as Sourcetree, for complex rebase process.

Further Reading

For more on writing quality git commit messages:

• Chris Beams: How to Write a Git Commit Message
• AboutCode: Writing good Commit Messages
• tbaggery: A Note About Git Commit Messages
• Contribution Guidelines — Zephyr Project Documentation
  

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

For more valuable processes to follow:

• Processes that Aid Embedded Systems Development