Automate your versioning (part 3)

Now it comes the final part of our 3 part series of automating your versioning with git based projects (maybe 5, if you include releasing and deploying part).

Below I am posting the links for the complete series, if you want read it all:

In the first part and second part you learned how to create proper commit messages and more importantly you learned how to setup a linter to make sure you are doing the right thing.

This post it will be more about using one specific tool for generating your versions and changelog if you wish that.

Standard Version

If you followed the last post, I wrote about installing NodeJS environment and a linter for your commit messages. So, I am assuming you already have it installed for the next steps.

Install Standard Version

The tool I am using is called “Standard Version“. It is a NodeJS based tool used to automate the versioning and also generating Changelog. Although there are plenty of tools available for doing it, I choose this one, because:

Already had NodeJS installed in my machine;
Not all tools worked very good with non JS projects, with this one I didn’t have many issues.

You always can choose another tool, as there are many tools with different languages.

Here is the code. It installs it globally.

npm install -g standard-version

It should take a few seconds and then you are done.

Testing the tool

The first thing you can do it is to test the tool. If you did the right configuration, you can test using the dry-run mode, which simulates the tool in real action. You don’t want to run without this flag at first time, because it would perform all the steps, including committing.

standard-version --dry-run

Doing this, it will perform the “life cycle” as it would do if it was in real action, including showing the lines that it would add to Changelog.

There are plenty of configurations for the “standard-version” command, as skipping some of the steps, as example:

You don’t want to commit after running the command, use “— skip.commit” flag
You don’t want to generate Changelog, use “—skip.changelog” flag.

For every step, you have a similar command to alter or skip the step. One thing that I really liked about this tool, is that it is highly configurable. That is my next topic.

If everything is ok, you can settle down your new version (preferable on main branch). If some reason it doesn’t work calling the “standard-version” you can prefix with “npx”.

npx standard-version
git push --follow-tags origin main

Configuring the Standard-Version

As it is not a JS Project (my case mostly LabVIEW Projects), you can’t do most of the configuration and command customization using the “package.json”, in this case you will need the configuration file named “.versionrc”

This configuration file is a JSON file which holds most of the settings for running the standard version in your project.

In the next sections, I will show some fields you want to configure:

Bump File

There are many reasons you would want to have a bump file (it can be even a plain text file if you wish), in my case I took advantage of the .versionrc file itself to fill this job. More information for bump file and the .versionrc configuration is in the documentation of standard-version.

"version": "",
"bumpFiles": [
    {
      "filename": ".versionrc",
      "type": "json"
    }
  ]

In this case I am pointing that my bump file (there could be more than one) is the “.versionrc” itself, and it is a JSON file. In this case, the file must have a string field named “version”. Now every time, I run the command it will update versions in this file.

Changelog Configuration

If you don’t like the default Changelog headers, you can set the headers using the header field:

"header": "# Changelog\\nAll notable changes to this project will be documented in this file.\\n\\nSee [standard-version](<https://github.com/conventional-changelog/standard-version>) for commit\\nguidelines. This project adheres to [Semantic Versioning](<https://semver.org/spec/v2.0.0.html>)."

Now, the Vhangelog is going to be generated with this header on every run.

“I already have a changelog in my project, what can I do?”

Delete the header from the existing and everything until the latest version, and from now on, the standard-version will be responsible for appending to the top of the file, the header and the new versions.

Types Configuration

By default, only two types are taken into account when writing the changelog file: feat and fix.

These two types are the main ones responsible for bumping versions, whereas the other types will only be “supporting actors”.

You can change the types which will appear, by including these other types in the configuration file:

 "types": [
    {"type": "chore","section": "Others","hidden": true},
    {"type": "feat",  "section": "Features","hidden": false},
    {"type": "fix","section": "Bug Fixes", "hidden": false },
    {"type": "docs","section": "Docs","hidden": false },
    {"type": "style","section": "Styling", "hidden": true},
    {"type": "refactor","section": "Code Refactoring","hidden": false},
    {"type": "perf", "section": "Performance Improvements","hidden": false},
    {"type": "test","section": "Tests","hidden": false},
    {"type": "build","section": "Build System","hidden": true},
    {"type": "ci","section": "CI","hidden": false}
  ]
}

So, now you can turn on and off these sections in the Changelog as you wish.

Including in your CI

In the latest part you would like to include these steps into your CI process, so you can automate this task. For this part, you may want to read my posts and see an example project at Gitlab.

So, for now that’s it, an another post to increment productivity, and if this helped you or you have any doubts, don’t forget to leave your comments below.

3 thoughts on “Automate your versioning (part 3)”

Pingback: Automate your versioning (part 2) – Felipe's Thoughts
Pingback: Automating your versioning (part 1) – Felipe's Thoughts
Pingback: Deploy your project in Gitlab CI – Felipe's Thoughts