Open Cyclonit opened 3 months ago
Thanks for opening your first issue at git-cliff! Be sure to follow the issue template! ⛰️
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:
[changelog]
section![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.skip_releases_pattern
can be just skip_pattern
.releases_order_by
-> order_by
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?
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.release.releases_order_by
to release.order_by
.commit.commits_sort_order
to commit.sort_order
.commit.max_commit_count
for limit_commits
? Sounds better to me, because I don't like unnecessary abbreviations.commit.split_commits_by_line
to commit.split_commits_by_newline
.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.
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?
I'd also like to ping @MarcoIeni for getting some thoughts on this, since he's using git-cliff-core
for release-plz
😊
Is there an existing issue or pull request for this?
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
List of changes:
changelog.footer
tochangelog.footer_template
to match naming forchangelog.body_template
.changelog.trim
tochangelog.trim_body_whitespace
to be more descriptive.git.filter_unconventional
: a Renamed toexclude_unconventional_commits
, becausefilter
can be misunderstood to be inclusive. b Moved from[git]
to[changelog]
, because it excluding changes is a function of the changelog.git.protect_breaking_commits
: a Renamed toretain_breaking_changes
to be more descriptive. b Moved from[git]
to[changelog]
, because retaining changes is a function of the changelog.git.filter_commits
: a Renamed toexclude_ungrouped_changes
to be more descriptive. Due tosplit_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.[release]
for options that act on the level of releases.git.tag_pattern
: a Renamed totags_pattern
to be more descriptive by including the purpose of the tags. b Moved to[release]
.git.ignore_tags
: a Renamed toskip_tags_pattern
to be more descriptive. b Moved to[releases]
.git.topo_order
: a Renamed toorder_by
to be more descriptive. b Changed type to an enum with optionstime
andtopology
. c Moved to[releases]
.[git]
to[commit]
to reflect that these options relate to operations on the level of commits.git.sort_commits
a Renamed tosort_order
to be more descriptive. b Renamed possible values tonewest_first
andoldest_first
to be more descriptive.git.split_commits
tosplit_commits_by_newline
to include that they operate on a line by line basis.git.skip_tags
toexclude_tags_pattern
._pattern
is used on all regex patterns.exclude
is more descriptive becauseskip
has a different meaning in the contest of releases.git.commit_preprocessors
tomessage_preprocessors
to emphasize them modifying the message and no other property of the commit.git.conventional_commits
toparse_conventional_commits
to be more descriptive.Tasks
config.rs
-- rename properties -- update descriptions -- rearrange sectionsconfig.toml
Alternatives considered
none
Additional context
No response