changelord.js/README.md

116 lines
2.7 KiB
Markdown
Raw Normal View History

2023-05-16 15:24:15 +00:00
# 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
## 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.
$ 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.
#### 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
2023-05-18 18:04:51 +00:00
### `changelord validate`
Validates the changelog source against its json schema.
2023-05-18 15:09:33 +00:00
### `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
2023-05-18 17:03:01 +00:00
^(?<type>[^: ]+):\s*(?<desc>.*?)(\[(?<ticket>[^\]]+)\])?$
2023-05-18 15:09:33 +00:00
The regular expression must capture a `desc` field, and may
capture a `type` and `ticket` as well.
2023-05-16 15:24:15 +00:00
[blog]: https://techblog.babyl.ca/entry/changelord/
[original]: https://metacpan.org/dist/App-Changelord/view/bin/changelord