# 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][original]. You can
read its [introductory article][blog] 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.

[blog]: https://techblog.babyl.ca/entry/changelord/
[original]: https://metacpan.org/dist/App-Changelord/view/bin/changelord