changelog-flow

CLI tool for creating, updating and maintaining CHANGELOG files. Because everyone needs to changelog once in a while.

changelog-flow makes it easy to keep your version of package.json up-to-date, generate CHANGELOG data, store it in a reusable json file, and finally automatically generate a CHANGELOG file (in markdown).

The structure of the log data generated with changelog-flow adheres to the Semantic Versioning specifications and the resulting CHANGELOG file is based on the guidelines by Keep a Changelog. Updated files are also automatically committed (you can opt-out) to git, following the GitFlow branching model (you can opt-out).

This tool is under development, PRs are welcome!

Installation

The easiest way to use changelog-flow is to intall it globally:

npm i -g changelog-flow

or

yarn global add changelog-flow

changelog-flow handles some git operations via the command line. To perform such git operations, you also need to have installed the git CLI. To install it, please refer to Getting Started - Installing Git. Alternatively, you may skip all git-related operations with --sg.

Git and GitFlow support

changelog-flow makes it easy to commit all newly created or modified files, and follow the GitFlow branching model in the process.

Before running nearly any action, changelog-flow checks if there are files to commit in the current branch. If so, it asks you for a commit message, and then it commits and pushes them to the remote repository.

Additionally, changelog-flow provides few quick commands to easily create and close feature branches, and stash changelog entries in a temp store to easily add them in future releases.

Usage

Open a terminal window where the package.json file of your project is located.

Run: cglg, the CLI will then ask you whether you want to:

• stash: stashes new log entries for a future update
• newFeature: starts a new feature
• closeFeature: closes current feature
• newRelease: creates a new release
• closeRelease: close current release
• md: build the CHANGELOG.md file

You can skip this step by passing the argument --action in terminal (e.g. --action=stash, see #Options).

Stashing new log entries for a future update

Allows you to add changes to a temporary property in changelog.json.

You will be asked what kind of change you want to add:

• added: for new features;
• changed: for changes in existing functionality;
• deprecated: for soon-to-be removed features;
• removed: for now removed features;
• fixed: for any bug fixes;
• security: in case of vulnerabilities.

You will then be asked to enter the description of the new log item. Be sure to write good git commit messages!

changelog-flow will then ask you if you want to

• Add another change: takes you back to the change type selection to repeat the process for a new log entry;
• Save changes and update the CHANGELOG: saves the changes in the temp property in changelog.json.

Starting a new feature

Useful to follow the GitFlow branching model.

Selecting this option will help you to create a new feature branch that follows the naming structure feature/[name-of-the-feature].

Closing the current feature

Useful to follow the GitFlow branching model.

Selecting this option will:

• merge on develop the current feature branch (if compliant with the structure feature/[name-of-the-feature]);
• delete the local and the remote feature branch.

You will then be asked if you want to Stash new log entries for a future update.

Creating a new release

You will be guided through the process of creating a new release of your project.

Versioning

changelog-flow will ask you what kind of update you are making, based on the Semantic Versioning specifications:

• patch: for making backwards-compatible bug fixes;
• minor: for adding one or more functionalities in a backwards-compatible manner;
• major: for making incompatible API changes.

You can also skip this step by setting the updateType variable when running the command cglg (see #Options).

You will then be guided through the process described for Stashing new log entries for a future update. In this case, once done, selecting Save changes and update the CHANGELOG will:

• update the version in package.json;
• save all new changes in changelog.json under the new version number with the current date (YYYY-MM-DD);
• generate the CHANGELOG file in markdown.

Git and GitFlow support

Unless you opt-out of GitFlow (see #Options), changelog-flow will also:

• close the current feature branch (see Closing the current feature);
• create a new release branch (release/[version-number]);
• commit and push all changes.

Options

| Arg | Type | Description | Default | |--------|------|-------------|---------| | p | [string] | sets updateType to patch | undefined | | f | [string] | sets updateType to minor | undefined | | m | [string] | sets updateType to major | undefined | | sg | [boolean] | skips all git operations | false | | sf | [boolean] | skips all GitFlow operations | false | | noTag | [boolean] | skips adding a tag for the new release | false | | action | [string] | sets the action to be performed | undefined |

Usage esample:

cglg --p --sf --action=newRelease

If the updateType argument is omitted, the CLI will ask to pick it.

Closing the current release

Useful to follow the GitFlow branching model.

Selecting this option will:

• merge on develop the current release branch (if compliant with the structure release/[name-of-the-feature]);
• merge on master the current release branch (if compliant with the structure release/[name-of-the-feature]);
• delete the local and the remote release branch;
• ask if a new tag should be created. If so, a new tag vX.X.X will be created and pushed to origin.

Building the CHANGELOG.md file

You can manually rebuild the CHANGELOG file by selecting the second option after running cglg.

changelog-flow will generate the markdown file right away in the current working project based on the contents of changelog.json.

License

MIT.