Writing conventional commits with commitizen

Kent C. Dodds
InstructorKent C. Dodds

Share this video with your friends

Send Tweet
Published 7 years ago
Updated 4 years ago

Because semantic-release requires a specific message format, it's easier to follow this convention using a tool called commitizen. In this lesson, we'll use it to write our first conventional commit message.

[00:00] Now that we have our semantic release all set up, we need to start following the conventions that semantic release uses to determine what version to bump. These conventions are the same conventions that Angular uses to update its change automatically. Let's go ahead and look at those.

[00:17] Here in the Angular contributing document, we can see that they had these commit guidelines. They're very specific commit message format. You have your header, a blank line and a body, a blank line and then footer.

[00:31] The type here is how semantic release knows whether to update your minor version if you specify feature, or a patch version if you specify a fix. Then, if you have a breaking change, then, those are specified in the footer as breaking change.

[00:50] You can read over this convention. It's pretty strict. To make this a little bit easier, we have a tool called Commitizen that makes creating these commit messages much easier. Let's go ahead and install that now.

[01:05] We'll run NPM install as dev dependencies Commitizen and cz-conventional-changelog. Commitizen is going to allow us to write these commit messages. The cz-conventional-changelog is going to ask us the questions to actually generate this commit message.

[01:25] If we look at our package JSON, we've added a cz-conventional-changelog and Commitizen. Commitizen adds a binary to our node modules directory call gitcz.

[01:39] We can access this binary in our scripts. That's exactly what we'll do. We'll create a script called commit. We'll just simply reference gitcz. Then, we need to tell gitcz that it needs to use the cz-conventional-changelog.

[01:58] To do this, we say the inner package JSON, cz config, and then, we specify the path is node modules/cz-conventional-changelog. Now, with this in place, if we look at our status, we have a new file and a modified file. Let's go ahead and add everything.

[02:24] Let's expand this out a little bit. We'll run our first commit message. Let's make sure that we've staged everything that we want to have committed in this commit. Then, we can run NPM run commit. Now, it will prompt us for the different sections of our conventional changelog convention that we're following.

[02:43] For us, the changes that we're adding are related to the build. I'm going to mark that as a chore. We'll simply say this is part of the build, or maybe releasing. We write our description, add Travis config, conventional commit, and semantic release.

[03:09] A longer description of this change, we can omit. Any issues or breaking changes if there were any, we'd say, causes number four. In fact, let's go ahead and do this right now. We'll go into our Star Wars name repository. We'll create a new issue.

[03:27] Simplify releases with semantic release and Commitizen. We'll submit that new issue. Then, this is issue number one. We'll say, it causes number one. If there were any breaking changes, then, we would add those there. Our commit succeeded.

[03:49] If we do a gitlog, then, we can see we have a chore releasing add Travis config conventional commit. If we'd added a body, it would appear here. Then, we say that it causes number one. That is setting up Commitizen with your project. Let's go ahead and review.

[04:07] What you need to do is you run NPM install, Commitizen, and cz-conventional-changelog. Then, you configure Commitizen with cz config and specify a path to the conventional changelog.

[04:22] Then, we also added a script here for commit that just simply references the bin that Commitizen gives us called gitcz. Then, we staged all of our changes, and then, run NPM run commit to actually commit our code.

[04:37] That's how you set up Commitizen in your project to simplify creating the conventional commit messages that semantic release uses to release your library.

David Poindexter
David Poindexter
~ 7 years ago

Heads up, for now, you need to make sure the version of cz-conventional-changelog is 1.1.2, else you'll probably get an error:

Potentially unhandled rejection [3] Error: Error loading "word-wrap" at file: ...

~ 6 years ago

I ran into problems with commitizen 2.8.0 -- it wouldn't commit anything (as per this issue https://github.com/commitizen/cz-cli/issues/205). Using 2.7.6 works.

Sung Kim
Sung Kim
~ 2 years ago

Angular commit message convention: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit