How Can I Automatically Bump Versions in My Project Using Conventional Commits?

In my regular development process, I’ve been following the conventional commits standard to ensure my commit messages are not only consistent but also useful in generating version numbers and changelogs. This helps in maintaining a systematic version control system which is crucial for trackability and understanding project evolution, especially when working in a team or for future references. Recently, I was tasked with automating the version bumping process based on the types of commits; a very practical scenario especially when trying to streamline CI/CD processes.

Understanding the Commit Message

Firstly, let’s decode the structure of a conventional commit message:

fix(TCM-1010): Web App / Manage Item Templates: The last item template in the table is cut off. Also the actions for this item are cut off

Breaking it down:

• fix indicates that this commit is a patch for fixing a bug, which, according to semantic versioning, will result in a patch version bump (e.g., from 0.0.1 to 0.0.2).

• TCM-1010 is likely an internal reference to a ticket in a project management tool.

• The rest describes what was fixed.

Automating Version Management with semantic-release

To automate the version bump based on commit messages like the above, I decided to use a tool named semantic-release. This tool automates the versioning and package publishing process based on semantic version guidelines and the commit messages history.

Setting Up semantic-release

To set up semantic-release in my project, I began by installing it along with its necessary plugins. Here’s how you can do it too:

1. Installing semantic-release and plugins

Open your terminal and run:

npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git

1. Configure semantic-release

Semantic-release uses a configuration file to manage how versions are bumped and how changelogs are generated. You can create a .releaserc or semantic-release.config.js in your project root. Here’s a basic setup:

module.exports = {
     branches: ['main'],
     plugins: [
       '@semantic-release/commit-analyzer',
       '@semantic-release/release-notes-generator',
       '@semantic-release/changelog',
       '@semantic-release/npm',
       '@semantic-release/github',
       [
         '@semantic-release/git',
         {
           assets: ['package.json', 'CHANGELOG.md'],
           message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
         },
       ],
     ],
   };

This configuration does the following:

• It analyzes commits.

• It generates release notes.

• It updates the changelog.

• It updates the package version and publishes to npm.

• It publishes the release on GitHub.

• It commits changes to package.json and CHANGELOG.md back to the repository.

1. Add semantic-release to your CI workflow

In your CI configuration file (e.g., .github/workflows/node.js.yml for GitHub Actions), add a step to run semantic-release:

- name: Release
     run: npx semantic-release
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Ensure you have GITHUB_TOKEN and NPM_TOKEN set up in your repository secrets for authentication.

Testing the Setup

Before merging everything into the main branch, it’s crucial to test your setup. Use feature branches to test the automated process. Ensure that the commits in your feature branch follow the conventional commit format and watch how semantic-release responds.

Observations and Next Steps

After implementing this automated system, I noticed a significant improvement in how efficiently new versions were being rolled out. The automation saved time and reduced human errors. For future improvements, considering adding more granular control over different types of releases (major, minor, patches) could be beneficial, tailoring it more closely to the team’s needs.

Implementing an automated semantic versioning process using semantic-release has been a game-changer in maintaining the project’s lifecycle. It ensures rigorous standards and also simplifies the contribution process for new team members.