add readme

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.