modif/README.md

52 lines
1.8 KiB
Markdown
Raw Permalink Normal View History

2024-11-09 20:20:53 +00:00
# Modif
Forgejo unfortunately doesn't support autogenerating release changelogs, and while a lot of tooling already exists out here to tackle that sort of problem, it often does far too much extra for my taste. Thus, `modif` seeks to do one thing and do it well: generate simple markdown changelogs from commit history data (and later, validate that commits comply with a desired format for those logs).
## Install
This isn't published anywhere, but can be installed directly from source control via `pipx` or `pip`:
```sh
# With pipx
pipx install git+https://forge.karnov.club/marc/modif.git
# With pip
pip install git+https://forge.karnov.club/marc/modif.git
```
The repository can also be pulled down to put it together yourself.
## Usage
### Generating changelogs from commit ranges
Changelogs can be generated based on a start and end reference:
```sh
modif log --from=<reference> --to=<reference>
```
Using the `--raw` flag will output the changelog markdown without any colours or headers - the output otherwise has
extra messaging that isn't part of the changelog itself.
### Commit format
Some assumptions are made about commit message formatting that will later be made more configurable. It is expected that commits conforms to the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) scheme.
2024-11-12 03:53:38 +00:00
### Configuration
The groupings can be configured using a YAML file formatted as follows:
```yaml
groups:
- label: <Heading to identify the group with in the generated log>
prefixes: [<prefix1>, <prefix2, ...]
- label: ...
prefixes: ...
```
Each group is headed by its `label` value and contains a list of all the commits matching the prefix selection for that group.
If not supplied, a default configuration (see `modif.configuration.get_default_config`) is substituted in.