Conventional-Logs

This package is a CLI utility tool for generating a CHANGELOG using Conventional Commits specification as a basis. By writing clean commits, it allows smaller projects to document changes between versions and update the Semantic Version accordingly.

Installing Conventional-Logs

This package can be installed locally to devDependencies:

npm i -D conventional-logs

The package can be executed through an package.json script, or directly in the terminal:

"scripts": {
    "updateChangelog": "npx cologs"
}

How it Works

1. A user performs a merge --squash on a branch into the master branch, followed by a commit that matches Conventional Commit specifications.
2. Assuming the main branch is ready to be released, the user runs cologs to parse main branch commits to then add to the local CHANGELOG.md.
3. cologs will automatically bump the package.json version appropriately and commit the changes to CHANGELOG.md.
4. The CHANGELOG.md commit will be given a git tag of v<version_number> for future reference.

Initializing CHANGELOG.md and First Release

This will create the CHANGELOG.md file for the first release of the project. Conventional-Logs will use the package.json version declared by the user as the intial release.

npm cologs --first-release

Once the first git tag is created, subsequent calls to cologs will add all commit messages to CHANGELOG.md since the previous tag.

Specifying Additional Files for Version Updates with --bumpList

Some projects can have files that need to have an internal version number updated to match packge.json. An additional configuration file can be defined anywhere in the project to specify these files.

mkdir configDir # An exmaple directory where bumpList.json is stored

Create a file name bumpList.json and create a single property called files with a value containing an array of strings. Each string entry is the an name of the file that needs an internal version number updated.

{
  "files": ["fileToUpdateOne.json", "fileToUpdateTwo.json"]
}

Conventional Logs will do a recursive search to find the location of these files during runtime. Only the name of the file should be provided, and should not include the local or absolute path. Internally, regex is used to identify a SemVer pattern in the file to change the number to the updated package.json version number.

The --bumpList flag can then be used, followed by the absolute path to the bumpList.json. the forward slash must be ommited.

npx cologs --bumpList configDir/bumpList.json