You know that when you are writing code and you make a git commit to your code? You know that when you make a commit, you are asked to type a message for that commit, right?
Conventional commits are a set of rules to follow for what to type for your commit messages. For example, let's say that you add a new feature to your latest app where users can upload a photo for their profile. Instead of writing a commit message like this: Add feature so users can upload profile picture for profile, you would write a commit message like this: feat(profile): user can upload profile picture. Notice that when you read both messages, they both mean the same thing. However, they are written in 2 different formats. When you write your commit message in the later format, we call that a Conventional commit.
Conventional commits are becoming more popular today and for good reason. Conventional commits are not only more descriptive to read, but they are written in a format that a computer can understand better. When a computer can understand something, we can automate things!
We can use conventional commits to automatically generate changelogs or bump the semantic version of your software when you make a new deployment.
There is not 1 format for writing conventional commits. There is the "Angular format", "Ember format", "jQuery format", and more. This document is going to go over the Angular format, only as it's a popular option.
When you write a commit message, follow this template:
<type>: <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Note: Any line of the commit message cannot be longer 100 characters.
Let's get into each of the parts above:
<type>(Required) - Must be one of the following keywords.
Note: The type must be all lowercase and end with : .
<subject>(Required) - Pretend you're writing an email. This is the subject line of the email that defines a one line description of the commit.
Note: The subject must follow these rules when writing them.
-
<body>(optional) - Think of this like an email. In the body, this contains a longer description of the commit. You can explain why you made this commit, for example. -
<footer>(optional) - If this commit introduces a breaking change, specify it in the footer. If you're unsure what a breaking change is, read this section of the document. If there is a breaking change, type it like this:BREAKING CHANGE: type the message here explaining the breaking change.
The footer also contains links to GitHub issues that this commit fixes, if there is one.
I suggest you read through all of the examples below to understand this template better.
Let's say that you...
- ...added a new feature to your app.
feat: add ability for user to upload photo for profile
Tip: Remember, you can include an optional body for your commit, but for feature additions it's not needed sometimes. The subject many times can explain the feature.
- ...fixed a bug:
fix: crash when user uploads photo for profile
Crash was because uploaded files too large.
Closes: https://github.com/foo/repo/issues/2
Tip: This commit message shows a body and a footer. You know that we have a body and a footer because there is a blank line separating the subject, body, and footer.
- ...edited some of the documentation for the project
docs: add section about file upload limits
This update is for the internal team docs, only.
Tip: This commit has a subject line and a body line, only. No footer. The body and the footer are both optional. There is no requirement to include either of them or both of them.
- ...run lint tool to format source code files
style: format source files
Forgot to run lint tool for previous commits.
- ...changed a feature in your app but it adds a breaking change
feat: edit profile first and last name required
BREAKING CHANGE: First and last name are now required parameters when editing profile. Existing profiles are untouched but the client app needs to update to require this paramter.
Tip: See the subject explains that we made the first and last name required. Then, the
BREAKING CHANGE:line explains this change in more detail. This sample commit message does not include a body for example purposes to show the body is optional when a footer exists, but for this commit a body would be good to have to explain why this change was put into place.
When you write a conventional commit message, you need to give a <scope>. The scope might be: fix, feat, docs, or something else.
Well, what do you do if you are working on your code for a whole day. You are super productive and you write tons of code. You fix multiple bugs, add a couple new features, change some configuration files, etc. What <scope> do you give for this huge change?
Well, you actually made a mistake. Instead of making 1 large commit, make multiple small commits. This means that you might need to practice some discipline when writing code to restrict the urge to jump into your code and make tons of drastic changes. Make a fix, make a commit. Add a feature, make a commit...
There are many ways to define breaking change in software. Each team can define it differently. A good dictionary definition is, A change in one part of a software system that potentially causes other components to fail; occurs most often in shared libraries of code used by multiple applications.
If you are writing software that other applications depend on (if you're creating a library, a network API, constructing a database schema) you need to consider breaking changes.
Think of it like this. Let's say you live in a house with another person. Each of you has a key to the house. One day your roommate changes the locks of the house. Changing the locks is a breaking change because now you cannnot get into the house without a new key. If your roommate replaces the kitchen stove or paints one of the bedrooms those are not breaking changes as they do not effect you because you are still able to cook with the stove and use the bedroom just fine. Even if the bedroom looks a little different and the stove looks brand new. If the roommmate replaced the stove with a different brand that you needed to learn how to use, that might be considered a breaking change.
Think of this example when writing code. When you are writing some code ask yourself, "Does this change effect other people using my software? Am I replacing the locks of the house (breaking) or just painting a room (not breaking)?".
If you are writing software that other applications do not depend on, changes are you will not have many breaking changes. For example: you are creating a web app. Web apps usually do not have other pieces of software depend on it. Instead, web apps tend to depend on many other pieces of software. Because of this, changes are you will not experience a lot of breaking changes. It's like you live in a house by yourself with no roommates. If you change the locks of your house, you don't need to tell anyone because you live alone.
Tip: Try to limit the number of times you make a breaking change. You would probably be really annoyed with your roommate if they replaced the locks of your house every week, wouldn't you?! It's understandable that there comes a time when a breaking chnage needs to happen. When that time comes, try to perform multiple breaking changes. Make multiple breaking change commits in 1 branch. That way you can give your roommate a small list of changes for them to do all at once.