Conventional Commits & Dynamic Changelog

What and why?

One of said ways can be to implement a dynamic CHANGELOG file.

A Changelog is generally a file where we keep all the changes made in an app or project such as bug fixes, new features, etc.

The use of a record file like this is for anyone who wants to be up to speed on which features are truly implemented in a project. Another great use for this is when the client asks “Where did this change?” or “When did we add that amazing feature?” we can pinpoint the where and when of the changes.

If you’d like some tips on how to develop an easy to read changelog you can check this small post: How to write a changelog

The issue with changelogs is that it takes the developers from their tasks to go write the changes they committed in a file and can be distracting. So we do what developers do best: we automate. 😎

How?

This section assumes you know what Git is and the basics on how it works.

If you read the first section you may have noticed that the way we write our commit messages can allow a machine to interpret it. This is possible by following a set of rules during our commit process.

Let’s assume we have a few changes in our code to commit and we stage them:

$ git add .‍When we’re ready to commit we’ll call the commit command with a message parameter where the magic will happen:-- CODE language-code line-numbers -- $ git commit -m "feat(homepage): Add alternative footer to the homepage ‍Implement the alternative version of the footer Add alternate icons in the mobile version of the footer Fixes issue #3"For the sake of clarity let’s break this message down to its structure:-- CODE language-code line-numbers -- <type>[optional scope]: <description> [optional body] [optional footer] ‍By structuring our messages this way machines can grab every single element — <type>, <description>, etc - and use it for the good of humanity-- I mean for the good of your project!In the next section, we will list what we can use in our commit messages.<h2 id="">Usage</h2>type: feat [ X.1.X - Minor] | fix [ X.X.1 - Patch] chore | docs | refactor | improvement [X.X.X - N/A] (There are other optional types but we’ll stick with these to keep things simple)It’s important to notice the feat and fix types bump up the version of the project correlating to a MINOR and PATCH (accordingly) in semantic versioning. The other types have no semantic versioning effect unless BREAKING CHANGE is specified.scope: (homepage): Short description of a section of the codebase enclosed in parenthesis followed by a colon and a spacedescription: Add alternative footer to the homepage Short description of the code changesbody: Implement the alternative version of the footer(…) A longer description of the commit, providing additional context about the changes. Must be placed one empty line after the descriptionBREAKING CHANGE: BREAKING CHANGE [1.X.X - Major] Must be indicated at the very beginning of the footer or body section of a commit and consist of the uppercase text BREAKING CHANGE, followed by a colon and a space. It bumps up the version of the project correlating to a MAJOR in semantic versioningfooter: Fixes issue #3 The footer should only contain additional issue references about the changes<h2 id="">What if I want to use custom names?</h2>Since this convention relies heavily on well-established keywords to increment the semantic versions of our app, using our own personal convention and still get the use of Conventional Commits is not an option at the moment.<h2 id="">Dynamic Changelog</h2>To dynamically update our changelog we’re going to be using a package called <a href="https://github.com/conventional-changelog/standard-version" target="_blank" id="">standard-version</a>First we install it:-- CODE language-code line-numbers -- $ npm i --save-dev standard-version‍Next we add a custom command in our package.json so it’s easier to use:-- CODE language-code line-numbers -- "scripts": {    &nbsp;"release": "standard-version" }‍Now we can use npm run release in place of npm version to update our app’s version and tags based on our CHANGELOG records<h2 id="">Extra tool (optional)</h2>If you don’t feel like memorizing the convention, commitizen has got you covered! It’s a command line utility that prompts you to fill out the required fields for each commit - which is pretty neat 👌<figure id="" class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div id=""><img alt="Image for post" src="https://cdn.prod.website-files.com/5f3fdb4ac2968afe2a89c98b/5f4f89b67a5c9b6c165aca2f_0*OmsGq1e9vwi4dlFw.png" width="auto" height="auto" loading="auto" id=""></div></figure>First we install commitizen globally.-- CODE language-code line-numbers -- $ npm install -g commitizen‍Then we install the necessary adapter:-- CODE language-code line-numbers -- $ npm install -g cz-conventional-changelog‍Now we create a .czrc file in our home directory-- CODE language-code line-numbers -- nano ~/.czrc‍And add a path property referring to the, globally installed, commitizen adapter:-- CODE language-code line-numbers -- { "path": "cz-conventional-changelog" }‍We can now run git cz instead of git commit to be greeted by the prompt! 👏<h2 id="">Video demo</h2>You check a video demo of the whole process working using the commitizen CLI below:<figure id="" class="w-richtext-figure-type-video w-richtext-align-fullwidth" style="padding-bottom:61.016949152542374%" data-rt-type="video" data-rt-align="fullwidth" data-rt-max-width="" data-rt-max-height="61.016949152542374%" data-rt-dimensions="590:360" data-page-url="https://vimeo.com/326551977"><div id=""><iframe allowfullscreen="true" frameborder="0" scrolling="no" src="https://player.vimeo.com/video/326551977"></iframe></div></figure>

What and why?

How?

Related Insights

What are the real benefits and risks of vibe coding?

Raycast: the perfect productivity tool for software engineers

DatoCMS vs Strapi: complete review