131 lines
3.3 KiB
Markdown
131 lines
3.3 KiB
Markdown
# 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
|