How to write commit messages in English

I’m not a native English speaker, so please understand if you see some mistakes in the wording.

I’m learning to write commit messages in English, to adapt to the open source community’s project commit message specification.

During the learning process, I found that there are many reference points for writing messages in English, apart from the differences in grammar, so I would like to record them in this article.

Need or not to need

A,An and The

Look at these two messages:

feat: add an article content rendering page
feat: add article content rendering page

The sentence “add article content rendering page” appears to be a fragment or a title rather than a complete sentence.

In such cases, the omission of articles like “an” or “the” can be acceptable, especially in titles, labels, or bullet points where brevity is often preferred.

However, in a full sentence, you would generally need an article to make it grammatically correct.

Here’s how you might expand it into a complete sentence: "Add an article content rendering page."

Do,Did and Done

Write your commit message in the imperative: “Fix bug” and not “Fixed bug” or “Fixes bug.”

This convention matches up with commit messages generated by commands like git merge and git revert.

Capitalization and Punctuation

Capitalize the first word and do not end in punctuation.

If using Conventional Commits, remember to use all lowercase.

Commit Formats

Conventional Commits

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

here are a full conventional commit example.

fix: fix foo to enable bar

This fixes the broken behavior of the component by doing xyz.

BREAKING CHANGE
Before this fix foo wasn't enabled at all, behavior changes from <old> to <new>

Closes D2IQ-12345

How to describe

To tell, don’t just to show.

Be direct, try to eliminate filler words and phrases in these sentences (examples: though, maybe, I think, kind of). Think like a journalist.

Journalists and writers ask themselves questions to ensure their article is detailed, straightforward, and answers all of the reader’s questions.

When writing an article they look to answer who, what, where, when, why and how.

For committing purposes, it is most important to answer the what and why for our commit messages.

To come up with thoughtful commits, consider the following:

Why have I made these changes?
What effect have my changes made?
Why was the change needed?
What are the changes in reference to?

Don’t expect the code to be self-explanatory.

Good or Bad

1 2	- git commit -m 'Add margin' - git commit -m 'Add margin to nav items to prevent them from overlapping the logo'

It is clear which of these would be more useful to future readers.

And there are another good examples:

- feat: improve performance with lazy load implementation for images
- chore: update npm dependency to latest version
- Fix bug preventing users from submitting the subscribe form
- Update incorrect client phone number within footer body per client request