Keeping an Automated Changelog in JavaScript

Having had it been a success for generating the CHANGELOG file in my project Terra Draw, I decide it would be good to share how that was achieved with the world. In this blog post we're going to look at how to implement an automated changelog using conventional commits, husky, commitlint and the standard-version package. You may have seen these types of automated changelogs previously in JavaScript projects and wondered how to implement them, this post will show you how.

What is a Changelog? #

A changelog is a document that records changes made to a software application as it changes over releases. It is typically used to keep track of bug fixes, new features, and other modifications to the project, and serves as a reference for users, stakeholders, and developers. The changelog helps to ensure transparency and accountability by documenting the history of changes to the project and can be used to understand the progression of the project over time. It is also useful for understanding how an API may have changed between different versions, or how a developer may need to adjust there code to the new library.

Conventional Commits #

Conventional commits are a standardized format for writing commit messages in a software development project, with a clear and consistent structure that includes a type, a scope, and a subject. This helps to improve the quality and maintainability of the project by making commit messages clear, concise, and informative. If we run git status on our project and it is using conventional commits, we should be able to easily understand what has happened in each commit and what effect it has had on the project.

You can see the conventional commits specification here. At the heart of it we will see commit messages that follow the following pattern:

<type>[optional scope]: <description>

Where type can be standard prefixes like fix, feat, chore, ci and others. For example we might make a commit like:

fix: remove endless loop when user clicks dropdown

Installing husky and commitlint #

Husky is a popular JavaScript tool that is used to manage Git hooks. Git hooks are scripts that run automatically at certain points in the Git workflow, such as before committing code or pushing to a remote repository. Husky makes it easy to manage and configure Git hooks in a project, allowing developers to enforce coding standards, run tests, and perform other automated tasks as part of the Git workflow.

We are going to leverage it here to ensure that commitlint is called on our commit. Let's install it:

npm install husky --save-dev

Then we'll need to activate it:

npx husky install

We'll then want to install commitlint into our project, which lints our commit messages to make sure they fit the conventional commit standard:

npm install @commitlint/cli @commitlint/config-conventional --save-dev

Then we can add the following package.json file:

    "commitlint": {
        "extends": [
            "@commitlint/config-conventional"
        ]
    },

You can also use a custom file commitlint.config.js if you so wish. Finally we will add the commit message hook which ensures that it adheres to the conventional commit standard.

npx husky add .husky/commit-msg  'npx --no -- commitlint --edit ${1}'

Creating an automated changelog with standard-version #

Now we have our commit message linting in place and we have a project with a conventional commit history, we can look at publishing our change log. For this post we'll use the standard-version library which allows generating of a CHANGELOG file from conventional commit history. First we'll need to install the the library:

npm i --save-dev standard-version

Let's update our package.json file here to include a release script:

  "scripts": {
    "release": "standard-version"
  }

Now that we have set up the release script, we can run our first release of our project doing the following command:

npm run release -- --first-release

For later releases you can drop the -- --first-release and just run:

npm run release

The release command will create a release tag on the commit, so you will probably want to push the tags to the git remote and also to actually publish the new package version to npm if it is registered there. You can do both of those like so.

git push origin main --tags

npm publish

Conclusion #

A changelog can be an essential tool for keeping track of changes in a software project and providing transparency to developers and other stakeholders. By using a standardized format for commit messages, such as the conventional commit format, and automating CHANGELOG generation with a library like standard-version, developers can save time and ensure that their projects have a clear and comprehensive record of changes. Overall, using a changelog and a tool like standard-version can help improve the quality and maintainability of a project, making it easier for developers to work collaboratively and for users to understand the progress and history of the project.

Published 06 Feb 2023