diff options
author | Marcel Müller <neikos@neikos.email> | 2023-04-29 13:19:40 +0200 |
---|---|---|
committer | Marcel Müller <neikos@neikos.email> | 2023-04-29 13:22:46 +0200 |
commit | 8e564163dfaaa5795e5c86b683acceff54cc296c (patch) | |
tree | 89b8c7e5a05ba27b548ecc38ebc724152171f4da | |
parent | 438d3c55349e85bde042734f9e3f874bf5680951 (diff) |
Expand readme with more info about commands
Signed-off-by: Marcel Müller <neikos@neikos.email>
-rw-r--r-- | README.md | 36 |
1 files changed, 33 insertions, 3 deletions
@@ -6,18 +6,48 @@ Changelog management tool for CLI. ## Usage -Changelogs are (by default) created with `cargo-changelog new` in in -`/.changelogs/unreleased`, using a timestamp for their names. +`cargo-changelog` is a tool to generate and manage changelog entries. + +It works in the following way: + +- Everytime you add/change/fix something and want to document it, you create a + new changelog entry with `cargo changelog new` +- Then, when a new version is released, you run `cargo changelog generate + <bump>` to move all unreleased changes to either the next patch/minor/major + version +- Finally, you re-generate the CHANGELOG.md file using `cargo changelog release` + +Here's how they work individually: + +### cargo changelog new + +`cargo changelog new` generates a new changelog file in the unreleased +changelog directory. Per default that is `.changelogs/unreleased`. +If interactive mode is enabled, which it is per-default, then you will be +prompted to fill in the fields of the changelog as well as a larger free-form +entry where you can explain the motivation and consequences of the changes. + +### cargo changelog generate <bump> Once you are done with one release, `cargo-changelog generate <version>` (for example `cargo changelog generate minor` for the next minor version) will take all unreleased changelogs and move them to `/.changelogs/0.1.0` (if "0.1.0" is your next minor version - you can of course also specify an explicit version with the `generate` subcommand). + +### cargo changelog release + After that you can create your final `CHANGELOG.md` file using `cargo-changelog release`. -You can configure `cargo-changelog` in `/.changelog.toml` and add mandatory or +This will take all released changelog entries and generate a new file, +overwriting the old. + +------- + +## Configuration + +You can configure `cargo-changelog` in `/changelog.toml` and add mandatory or optional metadata fields to your changelog entries. You can also specify a template file that gets used when rendering your changelogs to your final `CHANGELOG.md` file. |