changelord.js/README.md

Changelord, registrar of deeds extraordinaire

Changelord is a changelog manager scratching my particular itches. It's cli-based, and keep its data in a YAML file adhering to a well-defined schema.

The first iteration of changelord was written in Perl. You can read its introductory article on my blog.

Installation

pnpm install changelord

changelog-next directory

If you want to mininize merge conflicts in CHANGELOG.yml, you can set the option project.next_directory to a directory (typically ./changelog-next) that will hold yaml files containing the changes for the NEXT release. Each of those files is expected to have a list of changes.

CLI commands

Global options

--help

Outputs the list of commands and options.

--version

Outputs the changelord version.

--source

Specifies which source yaml file to use. Defaults to the CHANGELOG.yml file in the current directory.

changelord init

Initializes the changelog source file. The YAML file is made of three sections.

• project -- contains information and configuration about the project itself.
• releases -- the entries for the changelog proper.
• change_types -- defines all types of changes this project supports.

changelord add

Adds an entry to the NEXT release.

If project.next_directory is defined, the entry will be added to that directory instead of directly into CHANGELOG.yml.

$ changelord add --type=maint added a changelog to the project.

Options

• --type -- type of change.
• --ticket -- associated ticket.

changelord print

Renders the changelog as markdown.

Options

• --no-next -- don't show the NEXT section.

changelord cut

Cuts the next release. That is, resolves the NEXT version number based on the latest version and the changes in the NEXT section, and sets its date as today. Modifies the source file with the result.

If the project.next_directory option is present, all the changes in that directory are merged to CHANGELOG.yml and the files themselves are deleted.

Options

• --dry -- Resolves the next version but only outputs the resulting section without changing the source file.

changelord schema

Outputs the JSON schema defining the structure of the source file.

changelord upcoming

Outputs the changes listed in the NEXT release.

changelord latest-version

Outputs the latest non-NEXT release.

$ changelord latest-version
3.2.0

changelord validate

Validates the changelog source against its json schema.

changelord git-gather

Gathers change entries from git commits. If any are found, they are added to the changelog.

Lower bound of the git log

git-gather inspects the git log from the most recent of those three points:

• The last change in the NEXT release having a commit property.
• The last tagged version.
• The beginning of time.

Change-like git message

Git messages are compared to the regular expression configured at project.commit_regex. If none is found, it defaults to

^(?<type>[^: ]+):\s*(?<desc>.*?)(\[(?<ticket>[^\]]+)\])?$

The regular expression must capture a desc field, and may capture a type and ticket as well.