Revamp the configuration file

[Cyclonit]

Is there an existing issue or pull request for this?

• I have searched the existing issues and pull requests

Feature description

The current configuration lacks clear structure. The naming is inconsistent and some names are fairly non-descriptive. I believe git-cliff would profit from a refactor of the configuration options, command line parameters and update of the respective documentation.

This issue is intended as a basis for discussion. I have prepared a mock-up of how I would structure the configuration when starting from scratch. Below that is a numbered list of all of the changes such they can be discussed.

Any changes to the configuration will likely be breaking changes. Thus the target should be well defined, such that it is a one-off and not the start of many smaller changes.

Desired solution

Mock-up of the new config file

[changelog]
// A static header for the changelog.
header                            Option<String>                              // changelog.header

// Tera template for the changelog's body.
body_template                     Option<String>                           // changelog.body_template

// Tera template for the changelog's footer.
footer_template                   Option<String>                            // changelog.footer

// Whether to remove leading and trailing whitespaces from all lines of the changelog's body.
trim_body_whitespace              Option<String>                            // changelog.trim

// A list of postprocessors to modify the changelog using regex replacements.
postprocessors                    Option<Vec<TextProcessor>>

// Whether to exclude commits that do not match the conventional commits specification from the changelog.
exclude_unconventional_commits    Option<bool>                              // git.filter_unconventional

// Whether to fail generating the changelog if the history contains commits that do not match the conventional commits specification.
require_conventional_commits      Option<bool>

// If set to `true`, any breaking changes will be protected against being skipped due to any commit parser.
retain_breaking_changes           Option<bool>                              // git.protect_breaking_commits

// Whether to filter out changes that do not belong to any group.
exclude_ungrouped_changes         Option<bool>                              // git.filter_commits


[release]
// Regex to select git tags that represent releases (e.g. "v[0-9].*").
tags_pattern               String                                             // git.tag_pattern

// Regex to select git tags that do not represent proper releases (e.g. "rc"). Takes precedence over `release.tags_pattern`.
// Changes belonging to these releases will be included in the next non-skipped release.
skip_tags_pattern             String                                       // git.ignore_tags

// Whether to order releases chronologically or topologically.
order_by                  Enum: "time" / "topology"                 // git.topo_order


[commit]
// Whether to order commits newest to oldest or oldest to newest.           // git.sort_commits
sort_order                Enum: "newest_first" / "oldest_first"

// Whether to limit the total number of commits to be included in the changelog.
max_commit_count                     Option<usize>                             // git.limit_commits

// Whether to split commits by line, treating each line as an individual commit.
split_commits_by_newline             Option<bool>                              // git.split_commits

// Regex to select git tags that should be excluded.
// Commits with these git tags will not be included in the changelog.
exclude_tags_pattern              String                                    // git.skip_tags

// A list of preprocessors to modify commit messages using regex replacements prior to further processing.
message_preprocessors             Option<Vec<TextProcessor>>                // git.commit_preprocessors

// A list of parsers to extract links from identifiers found in commits. The extracted links can be used in the body template as `commit.links`.
// e.g. "PRJ-1234" -> "https://example.com/jira/browse/PRJ-1234"
link_parsers                      Option<Vec<LinkParser>>                // git.link_parsers

// Whether to parse commits according to the conventional commits specification.
// Sets the commits' `group`, `scope`, `message` (= `description`), `body`, `breaking`, `breaking_description` and `footers`.
parse_conventional_commits         Option<bool>                             // git.conventional_commits

// A list of parsers using regex on the whole commit message taking presedence over conventional commit.
// Sets the commits' `group`. Optionally sets the commits' `scope`. 
commit_parsers                     Option<Vec<CommitParser>>                // git.commit_parsers


[remote.github]
owner   String
repo    String
token   Option<Secretstring>

List of changes:

1. Renamed changelog.footer to changelog.footer_template to match naming for changelog.body_template.
2. Renamed changelog.trim to changelog.trim_body_whitespace to be more descriptive.
3. git.filter_unconventional:
   a Renamed to exclude_unconventional_commits, because filter can be misunderstood to be inclusive.
   b Moved from [git] to [changelog], because it excluding changes is a function of the changelog.
4. git.protect_breaking_commits:
   a Renamed to retain_breaking_changes to be more descriptive.
   b Moved from [git] to [changelog], because retaining changes is a function of the changelog.
5. git.filter_commits:
   a Renamed to exclude_ungrouped_changes to be more descriptive. Due to split_commits being a thing, it makes more sense to refer to it working on changes instead of commits.
   b Moved from [git] to [changelog], because retaining changes is a function of the changelog.
6. Added section [release] for options that act on the level of releases.
7. git.tag_pattern:
   a Renamed to tags_pattern to be more descriptive by including the purpose of the tags.
   b Moved to [release].
8. git.ignore_tags:
   a Renamed to skip_tags_pattern to be more descriptive.
   b Moved to [releases].
9. git.topo_order:
   a Renamed to order_by to be more descriptive.
   b Changed type to an enum with options time and topology.
   c Moved to [releases].
10. Renamed [git] to [commit] to reflect that these options relate to operations on the level of commits.
11. git.sort_commits
    a Renamed to sort_order to be more descriptive.
    b Renamed possible values to newest_first and oldest_first to be more descriptive.
12. Renamed git.split_commits to split_commits_by_newline to include that they operate on a line by line basis.
13. Renamed git.skip_tags to exclude_tags_pattern. _pattern is used on all regex patterns. exclude is more descriptive because skip has a different meaning in the contest of releases.
14. Renamed git.commit_preprocessors to message_preprocessors to emphasize them modifying the message and no other property of the commit.
15. Renamed git.conventional_commits to parse_conventional_commits to be more descriptive.

Tasks

• refactor config.rs
  -- rename properties
  -- update descriptions
  -- rearrange sections
• update all config.toml
• update website
• refactor CLI parameters

Alternatives considered

none

Additional context

No response

[welcome]

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

[orhun]

I overall like it. I think we can have a subcommand such as git-cliff migrate-config to provide a smoother transition to the new config format.

A couple of comments:

• I like the new [changelog] section!
• Having a [release] section is smart but I don't think we need to prefix the options with release_ as well. For example:
  • release_tag_pattern can be just tag_pattern. Or maybe just select_pattern since tag vs. release might be confusing. OR exclude_tags_pattern for having symmetry with the [commit] section.
  • Similarly, skip_releases_pattern can be just skip_pattern.
  • releases_order_by -> order_by
• How about commits_sort_order -> sort_order
• limit_commits -> limit_num_commits
• split_commits_by_line -> split_commits_by_newline

That's just initial feedback, I will give this more thought over time. What do you think?

[Cyclonit]

• I updated the proposal to use release.tags_pattern and release.skip_tags_pattern. I believe exclude_tags_pattern is a worse choice, because the option works differently than commit.exclude_tags_pattern. For releases, the affected changes aren't excluded from the changelog, but moved into the next release.
• Changed release.releases_order_by to release.order_by.
• Changed commit.commits_sort_order to commit.sort_order.
• How about commit.max_commit_count for limit_commits? Sounds better to me, because I don't like unnecessary abbreviations.
• Changed commit.split_commits_by_line to commit.split_commits_by_newline.

[Cyclonit]

I made a small adjustment in changing exclude_ungrouped_commits to exclude_ungrouped_changes. Strictly speaking, the changelog doesn't work on commits. Due to split_commits being a thing, it makes more sense to refer to it working on changes instead.

To be exact, I would also consider changing the template context to use changes instead of commits, where each change references the commit it came from. This would introduce a cleaner separation between the concept of commits and the changes contained therein.

[orhun]

How about commit.max_commit_count for limit_commits? Sounds better to me, because I don't like unnecessary abbreviations.

That's good, or maybe max_commits?

To be exact, I would also consider changing the template context to use changes instead of commits, where each change references the commit it came from.

Do you mean the configuration file or the internal types?

[orhun]

I'd also like to ping @MarcoIeni for getting some thoughts on this, since he's using git-cliff-core for release-plz 😊