refactor(core): improve the generation API by orhun · Pull Request #1306 · orhun/git-cliff

orhun · 2025-11-04T11:36:39Z

Description

New Methods

init_config: initializes and writes a configuration file.
write_changelog: writes the generated changelog to a file or stdout.

Breaking Changes

Changelog::new now takes ownership of Config (Config instead of &Config).
Changelog::from_context and internal build methods also updated to take Config by value.
run now returns Result<Changelog<'static>> instead of Result<()>.

Refactors

Configuration initialization logic moved out of run_with_changelog_modifier() into the new init_config() function.
The main entry point (main.rs) now explicitly calls check_new_version(), init_config(), run(), and write_changelog() instead of relying on run() for all logic.
Example renamed from examples/run.rs to examples/basic.rs and updated to use the new API (write_changelog).

Minor Changes

check_new_version() made public.
Opt now derives Clone to allow reuse across function calls.

Motivation and Context

closes #1046

How Has This Been Tested?

Locally.

Types of Changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation (no code change)
Refactor (refactoring production code)
Other

Checklist:

My code follows the code style of this project.
I have updated the documentation accordingly.
I have formatted the code with rustfmt.
I checked the lints with clippy.
I have added tests to cover my changes.
All new and existing tests passed.

orhun · 2025-11-04T11:39:14Z

cc @marcoieni (for release-plz downstream)

codecov-commenter · 2025-11-04T11:49:12Z

Codecov Report

❌ Patch coverage is 7.89474% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 43.88%. Comparing base (ef65be6) to head (f6933a4).
⚠️ Report is 103 commits behind head on main.

Files with missing lines	Patch %	Lines
git-cliff/src/lib.rs	0.00%	22 Missing ⚠️
git-cliff/src/main.rs	0.00%	12 Missing ⚠️
git-cliff-core/src/changelog.rs	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1306      +/-   ##
==========================================
+ Coverage   43.86%   43.88%   +0.02%     
==========================================
  Files          23       23              
  Lines        2214     2220       +6     
==========================================
+ Hits          971      974       +3     
- Misses       1243     1246       +3

Flag	Coverage Δ
unit-tests	`43.88% <7.90%> (+0.02%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

ognis1205

nit: as mentioned on Discord, a few clones could be reduced.
See the suggestion for the exact changes. Otherwise, LGTM!
The arguments of run_with_changelog_modifier could also be reconsidered later.

orhun · 2025-11-09T20:00:20Z

Thanks for the great review! I applied your suggestions

ognis1205

Thanks for accepting the previous suggestion!

I left a suggestion regarding a point I missed in the last review. As an additional note, I changed the lifetime from 'static to 'a for Changelog<'a>. This allows the caller to decide the appropriate lifetime. Although we kept the 'a lifetime for flexibility, in practice the returned Changelog is always 'static because it owns all its data internally. This is mostly a stylistic choice, so feel free to ignore if you prefer.

I'm also quoting here the discussion from Discord about Cow:

Considering git-cliff as a CLI tool, currently the only place calling Changelog::new or Changelog::from_context is run_with_changelog_modifier, so I don't think using Cow<'a, Config> is necessary.

However, if we view git-cliff-core as an SDK that could be used by external applications, implementing impl<'a> From<Config> for Cow<'a, Config> and impl<'a> From<&'a Config> for Cow<'a, Config> and changing the arguments of Changelog::new/Changelog::build/Changelog::from_context to config: impl Into<Cow<'a, Config>> seems like a reasonable option. This would also preserve backward compatibility.

ognis1205 · 2025-11-10T08:17:01Z

In another thread, I discussed with @orhun the idea of changing the struct to something like:

pub struct Changelog<'a> {
    /// Releases that the changelog will contain.
    pub releases: Vec<Release<'a>>,
    /// Configuration used for generating the changelog.
    pub config: Cow<'a, Config>,
    header_template: Option<Template>,
    body_template: Template,
    footer_template: Option<Template>,
    additional_context: HashMap<String, serde_json::Value>,
}

and updating the API in Changelog::new / Changelog::from_context to:

pub fn new(releases: Vec<Release<'a>>, config: impl Into<Cow<'a, Config>>, range: Option<&str>) -> Result<Self>

I think this approach, using Cow<'a, Config>, makes sense when considering git-cliff-core as an SDK, since it maintains backward compatibility. On the other hand, since I'm not personally using git-cliff-core as an SDK, I'd like to hear the opinion of @marcoieni , who is implementing release-plz.

That said, I don't want to burden everyone with extra review work, so I think it's fine to proceed with the current approach for now. If any compatibility issues arise later, we can revisit and implement this change separately, it shouldn't require too much additional effort.

ognis1205 · 2025-11-11T10:27:00Z

As @orhun mentioned earlier, in the long term, we'll likely need a broader overhaul of git-cliff's lib.rs.

In particular, it might be worth reconsidering whether the Changelog struct should hold a reference to Config, own it directly, or not depend on it at all.

For this PR, I think we can proceed as is, but it could be good to open a separate long-term issue to track that discussion.

marcoieni · 2025-11-12T16:58:08Z

I have no time to review this unfortunately. Feel free to do all the updates you want. I'll just fix them in release-plz. If you bump the major version of git-cliff-core when publishing the breaking changes it would be great!

* `init_config`: initializes and writes a configuration file. * `write_changelog`: writes the generated changelog to a file or stdout. * `Changelog::new` now takes ownership of `Config` (`Config` instead of `&Config`). * `Changelog::from_context` and internal `build` methods also updated to take `Config` by value. * `run` now returns `Result<Changelog<'static>>` instead of `Result<()>`. * Configuration initialization logic moved out of `run_with_changelog_modifier()` into the new `init_config()` function. * The main entry point (`main.rs`) now explicitly calls `check_new_version()`, `init_config()`, `run()`, and `write_changelog()` instead of relying on `run()` for all logic. * Example renamed from `examples/run.rs` to `examples/basic.rs` and updated to use the new API (`write_changelog`). * `check_new_version()` made public. * `Opt` now derives `Clone` to allow reuse across function calls.

orhun · 2025-11-21T19:39:48Z

Thanks for the review again Shingo!

ognis1205 · 2025-11-22T15:14:38Z

Thanks for the review again Shingo!

No problem :) If there’s anything I can help with, just ping me anytime.

ognis1205 suggested changes Nov 9, 2025

View reviewed changes

orhun requested a review from ognis1205 November 9, 2025 20:00

ognis1205 suggested changes Nov 10, 2025

View reviewed changes

Comment thread git-cliff/src/lib.rs Outdated

Comment thread git-cliff/src/lib.rs Outdated

ognis1205 approved these changes Nov 16, 2025

View reviewed changes

orhun added 6 commits November 21, 2025 22:30

style: run rustfmt

d810d31

refactor: fix path comparison

41c7223

refactor: fix path comparison

2a66b3a

refactor: apply code review suggestions

48fddc4

refactor: remove static lifetime

f6933a4

orhun force-pushed the refactor/improve_generation_api branch from bf58b09 to f6933a4 Compare November 21, 2025 19:30

orhun merged commit 1e80739 into main Nov 21, 2025
91 of 93 checks passed

BrewTestBot mentioned this pull request Dec 14, 2025

git-cliff 2.11.0 Homebrew/homebrew-core#258593

Merged

Conversation

orhun commented Nov 4, 2025

Description

New Methods

Breaking Changes

Refactors

Minor Changes

Motivation and Context

How Has This Been Tested?

Types of Changes

Checklist:

Uh oh!

orhun commented Nov 4, 2025

Uh oh!

codecov-commenter commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ognis1205 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

orhun commented Nov 9, 2025

Uh oh!

ognis1205 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ognis1205 commented Nov 10, 2025

Uh oh!

ognis1205 commented Nov 11, 2025

Uh oh!

marcoieni commented Nov 12, 2025

Uh oh!

orhun commented Nov 21, 2025

Uh oh!

Uh oh!

ognis1205 commented Nov 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov-commenter commented Nov 4, 2025 •

edited

Loading

ognis1205 left a comment •

edited

Loading