23
art of writing a good commit message
Hi there, In this article, I will be discussing the importance of commit messages and I'll walk you through a format that will assist you in crafting effective commit messages.
“A commit message shows whether a developer is a good collaborator.”
-Peter Hutterer, Senior Software Engineer at Red Hat
A commit message is a short description of the changes you've made to a file added before committing the changes. It is one of the most common ways for developers to communicate with one another & important to properly express any changes so that someone else reading it isn't left in the dark.
If you browse through a random GitHub repository, you'll frequently come across an extremely random commit message that is not descriptive and is difficult to understand.
So, It is essential that you take the time to write a proper commit message. Good commit messages are important not only for the people working on the project with you but also for you to keep track of all your commits and know exactly what changes were made during that commit.
So, It is essential that you take the time to write a proper commit message. Good commit messages are important not only for the people working on the project with you but also for you to keep track of all your commits and know exactly what changes were made during that commit.
To compose a good commit message, I will recommend using This Commit Message Style Guide
type(scope): subjectbody (optional)footer (optional)The commit contains the following structural elements, to communicate intent to the consumers:
feat - a new feature
fix - a bug fix
docs - changes in documentation
style - everything related to styling
refactor - code changes that neither fixes a bug or adds a feature
test - everything related to testing
chore - updating build tasks, package manager configs, etc
A scope MUST consist of a noun describing a section of the codebase affected by the changes (or simply the epic name) surrounded by parenthesis. Example:
This contains a short description of the changes made. It shouldn't be greater than 50 characters, should begin with a capital letter and written in the imperative eg. Add instead of Added or Adds.
The body is used to explain what changes you made and why you made them. Not all commits are complex enough that they need a body, especially if you are working on a personal project alone, and as such writing a body is optional.
A blank line between the body and the subject is required and each line should have no more than 72 characters.
A blank line between the body and the subject is required and each line should have no more than 72 characters.
The footer is also optional and mainly used when you are using an issue tracker to reference the issue ID.
Good commit messages serve at least three important purposes:
Good commit messages serve at least three important purposes:
To speed up the reviewing process.
To help us write a good release note.
To help the future maintainers of Erlang/OTP (it could be you!), say five years into the future, to find out why a particular change was made to the code or why a specific feature was added.
To help us write a good release note.
To help the future maintainers of Erlang/OTP (it could be you!), say five years into the future, to find out why a particular change was made to the code or why a specific feature was added.
Example of a good commit message used by Udacity
feat: Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like log, shortlog
and rebase can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain to them.
Further paragraphs come after blank lines.
Bullet points are okay, too
Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
Some more simple examples :
feat: JIRA-123 -implement new set-group api
docs: added banner in README.md
While writing a commit message, keeping these things in mind
type(scope): subject
<body>
<footer>feat: The new feature being added to a particular application
fix: A bug fix
style: Feature and updates related to styling
refactor: Refactoring a specific section of the codebase
test: Everything related to testing
docs: Everything related to documentation
chore: Regular code maintenanceProvided in parentheses after the type of commit, describing parts of the code affected by the changes or simply the epic name.
feat(claims)
fix(orders)Short description of the applied changes.
feat(claims): add claims detail page
fix(orders): validation of custom specificationUse the body to explain what changes you have made and why you made them.
refactor!: drop support for Node 6
BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.Use this section to reference issues affected by the code changes or comment to another developers or testers.
fix(orders): correct minor typos in code
See the issue for details
on typos fixed.
Reviewed-by: @John Doe
Refs #133Let me know your thoughts and feedback in the comments section.