diff --git a/README.md b/README.md new file mode 100644 index 0000000..f801a87 --- /dev/null +++ b/README.md @@ -0,0 +1,106 @@ +# clpack + +clpack = ChangeLog pack + +This is a command line tool for keeping a changelog. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and can be customized. + +This tool aims to make change logging as streamlined as possible to encourage developers to do it +automatically for every bugfix and feature. This can be enforced as part of a CI pipeline. + +The entry format is kept simple and readable, so entries can be added manually as well - e.g. if some +contributors can't or don't want to use this tool. + +_The tool is meant to be used with Git, but it is not required - it's just more convenient, +as it can pre-fill some information from branch names._ + +## Advantages over keeping the changelog manually + +- **No merge conflicts to resolve** + - Each changelog entry (feature, bugfix) lives in its own file until packed into a release. +- **Support for multiple release channels** + - Normally, you have just one, default, release channel for stable releases - e.g from branch `main` or `master`. + - However, if you use separate branches for beta, preview, EAP, LTS etc., it is now possible to keep a separate + changelog file for each, which will be accurate even if fixes are backported, cherry-picked, merged from other + branches etc. +- **Issue numbers are extracted from branch names** + - Branches must follow a common pattern (configurable) for this to work, e.g. `1234-awful-crash`, + `SW-1234-make-ui-more-pretty` + - GitLab & YouTrack format supported by default +- **Uniform formatting & sections** - a template is pre-generated so developers just fill in the blanks for each + changelog entry +- **Automatic release dating** - date in configurable format may be added to your changelog file +- **Fully configurable** but also works out of the box for most projects + +## Building + +clpack uses stable rust. Compile with `cargo build --release`. + +The binary is intended to be called `cl` in your path. + +## "Getting started" + +1. Run `cl init`. Inspect and customize the config file `clpack.toml` as needed. +2. To log a change, on your feature branch, use `cl add` or just `cl` for convenience +3. To pack changelog entries for a release, run `cl pack`. + - If you use release branches with a common naming scheme, like `rel/3.14`, clpack is able to parse the version + and use it as a suggestion when asking for version number. The pattern matching is based on regex and is configurable. + +Changelog is written into `CHANGELOG.md`. This can be customized as well. + +## Minimal setup + +The changelog file is not required if you are happy with the defaults. + +1. Create folder called changelog in your project +2. Use `cl` in the root of your project. It will use default config and create its subdirectories automatically as needed. + +## Adding a changelog entry manually + +There is no "vendor lock-in" with clpack. You can simply add changelog entries with your text editor - e.g. +if you use a machine without the tool, or for contributors using exotic systems like Microsoft Windows +(although clpack, in theory, might be compatible). + +**Simply add a Markdown file like `my-bugfix.md` into `changelog/entries/`.** + +## Changelog entry formatting + +Whether you use clpack or do it manually, the actual entry is always a simple markdown file you edit in your preferred editor. + +To set the editor to use, use env variable EDITOR, e.g. vim, nano. You can also create an empty entry template using +clpack and later edit it in your IDE, just don't forget. + +- Empty lines are discarded +- Lines starting with `#` are considered a section name - e.g. Fixes, Improvements. Keep the section names consistent + across entries, as they will be grouped when packing the changelog for a release. Lines outside any section will go + in the front. +- All other lines will be included in the changelog, without any trimming or changes, and will stay together and in + the same order -> you can write multi-line entries with indentation. + +## Working with release channels + +Use this if you need to maintain separate release series, e.g. stable, lts, beta, eap, which share some commits +(with changelog entries). + +Normally, each channel is on its own branch or branches following a naming scheme, e.g. stable releases. This is not mandatory - if it fits +your needs, you can have multiple channels on the same branch, too - or e.g. create a throwaway release channel for each major release, +so you can keep backporting fixes and making releases from the older branch without merge conflicts in the changelog file. + +1. Define channels and branch matching rules in the config file `clpack.toml`. + - If there is no matching rule for a channel, i.e. it is selected manually, use empty string +2. When calling `cl pack` and there is more than one channel configured, the channel is auto-detected from the branch name. + - clpack will ask for channel confirmation, with the auto-detected channel pre-selected + - You may specify the channel directly by using e.g. `cl pack -x beta` +3. Each channel will have its own changelog file, by default called e.g. `CHANGELOG-BETA.md` + +## How it works internally + +- Each changelog entry is a markdown file in the folder `changelog/entries` +- clpack maintains JSON files in `changelog/channels` with a list of which entries were included in which release +- Changelog entries stay in their files even after making a release, so if you merge a stable branch into a testing + branch, you can create a changelog entry for a testing release, and it will include new fixes from stable as well as + changes made on the testing branch. +- When a large "epoch" release is made, you can delete (`cl flush` - TODO) the contents of the changelog folder. + - Do not delete the folder itself, clpack would complain it is missing. + - If you have a linear release history without multiple channels or backporting, you can do this after every release.