Generate multiple changelogs in different formats #572

Open taladar opened 4 months ago

Is there an existing issue or pull request for this?

[X] I have searched the existing issues and pull requests

Feature description

I am currently evaluating git-cliff as a possible changelog generator for future projects. A lot of the binary (as opposed to library) Rust projects I write use two changelog files, one in markdown format for GitHub/GitLab display and one in Debian format for cargo-deb Debian packages.

It would be useful to have the option to specify multiple outputs in the git-cliff config to cover use cases like this where multiple downstream tooling options each have their own prescribed changelog formats.

Desired solution

Some way to have multiple distinct sections in the cliff.toml for outputs. I am not that familiar with the config file format yet but most likely just having a TOML array of tables for the changelog section would be enough but I don't understand the tool well enough yet to know if values from other sections might also have to be duplicated.

Alternatives considered

It might be possible to just call git-cliff twice with different config files but then some of the work is done twice and some of the config is essentially in whatever script contains those calls.

Additional context

No response

Thanks for opening your first issue at git-cliff! Be sure to follow the issue template! ⛰️

Another use case for this: I'd like to use git-cliff for both GitLab releases (markdown changelog) and for notifying on Slack (minimal mrkdwn changelog).

Can you elaborate on what you'd like the workflow to look like? Assuming git-cliff supports multiple output configurations in one config file, what would you expect the cli command for generating both outputs in one run be?

Good question, I guess I'd want one at a time, so I'd want to specify a template name or a profile or something that could perhaps encompass more things.

Maybe a bit bloated. I'm just spitballing.

Personally for my use case I would prefer if I could specify all the options in the config file (e.g. whether to prepend, what the output filename is supposed to be,..) though an option to name each config and apply only one of the named configs wouldn't really conflict with that.

I just realized I'll probably solve all my problems by just using --config some-other-config.toml so never mind me.

Can you share how the config file should look like if we support multiple outputs? I don't think it is an easy thing to do without doing breaking changes (we will break stuff quite a bit in #559 anyways - so that's might be the right place to discuss this).

I still think you can simply solve this by running git-cliff multiple times with different configuration files. You can also use environment variables (e.g. GIT_CLIFF__CHANGELOG__BODY) to override values.

I have use cases for this too. I haven't implemented it for any of the projects with this need yet but I've had my eye on doing it for a while. As best I could figure with some playing around multiple config files with non-standard locations (like cliff-plain.toml and cliff-markdown.toml) does get the job done. It just isn't very ergonomic and suffers from tooling file clutter.

I would suggest the configs could look exactly like they do now, but have [changelog] and [workspace.metadata.git-cliff.changelog] keys be the default changlog style, but introduce a new CLI flag for --style or --variant or --template (naming is hard) that took it's settings from [changelog.<variant_name>] or [workspace.metadata.git-cliff.changelog.<variante_name>] instead.

I would also set it up so the default style was used for all keys except ones explicitly set in the variant, so project defaults could be setup, then overrides for specific styles/templates/variants/whatever they are called. This is part of why the current multi-config work around is not ergonomic: a whole lot of things end up duplicated between configs. For example I might want to have git.commit_preprocessors and many other settings under [git]/[workspace.metadata.git-cliff.git] just shared across all changelog variants, but have a variant that uses just a different git.commit_parsers setting that skips more or less things.

I like your suggestion @alerque - I think implementing this via [changelog.<variant_name>] and adding an argument for specifying a <variant_name> is the way to go.

Another option here will be to have an option to specify a "base" config and then add things above it (or an "include" statement) in the toml.

Or the same solution with a "simpler" implementation will be to change --config to get a vector of paths and then load it in order (the later may overwrite keys) so we can still share the "base" config and still have variants of different outputs

orhun / git-cliff