feat(changelog): support generating changelog for different branches

[braineo]

Description

close #750

Motivation and Context

When a project needs to maintain diverged branches and create changelog for each branch this change is necessary.

for example a project's v3 is a complete rewrite and the changes onward have nothing to do which v2 branch. While v2 is in maintenance mode that the fixes are not relevant to v3 anymore.

when creating changelog for v3, it is necessary not to include the changes in the v2 which are not even included in the current branch

How Has This Been Tested?

Screenshots / Logs (if applicable)

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.

[braineo]

although the result of test-topo-order is not matching the expected.md but i feel like the new behavior should probably be the expected result.

the test commit first tags v0.1.0 and v0.2.0, then it checks out v0.1 and creates a new v0.1.1 tag.

in my opinion the expected full changelog should contain v0.1.0 and v0.1.1 instead of v0.2.0 only see #750 @chrissi-p

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

Attention: Patch coverage is 23.07692% with 10 lines in your changes missing coverage. Please review.

Project coverage is 40.02%. Comparing base (08e761c) to head (bbb9617).

Files with missing lines	Patch %	Lines
git-cliff-core/src/repo.rs	33.34%	6 Missing ⚠️
git-cliff/src/lib.rs	0.00%	4 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #808      +/-   ##
==========================================
- Coverage   40.13%   40.02%   -0.10%     
==========================================
  Files          20       20              
  Lines        1645     1657      +12     
==========================================
+ Hits          660      663       +3     
- Misses        985      994       +9     

Flag	Coverage Δ
unit-tests	40.02% <23.08%> (-0.10%)	⬇️

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.

[orhun]

Thanks for the PR! The issue is more clear to me now and I'm considering to switch to this new behavior. However, I need some explanations about how this is supposed to work :)

[orhun]

Also, any idea why the topo order fixture is failing? I'm trying to understand the change of behavior and its relation to the topo order 🤔

[braineo]

Also, any idea why the topo order fixture is failing? I'm trying to understand the change of behavior and its relation to the topo order 🤔

Because the tags chosen for the changelog are different now.

[braineo]

@orhun i've updated the description and the test cases. can you take a look at it plz?

[orhun]

Well, I'm not fully convinced to go ahead with this. It breaks the topo order argument in a way that I don't understand.

Because the tags chosen for the changelog are different now.

Maybe you can expand this a bit?

[orhun]

Maybe there is a way of supporting both cases if the commits are on other branches?

I'm not really sure if this fix is worth breaking the topo order argument.

[braineo]

Well, I'm not fully convinced to go ahead with this. It breaks the topo order argument in a way that I don't understand.

Because the tags chosen for the changelog are different now.

Maybe you can expand this a bit?

those features are independent from each other. My change only affects "what" commits are chosen, while leaving "how" they are sorted untouched.

See the chart below if it helps:

When one project has both v1 and v2 branches. It is typical that v1 branch change log does not include the changes from v2 since the code never exists in v1. And vice versa. The red dash areas are the tags considered for change log depending on at which commit the dev executes git-cliff

[braineo]

hi @orhun

is the explanation good enough or you are still looking into more details?

[orhun]

those features are independent from each other. My change only affects "what" commits are chosen, while leaving "how" they are sorted untouched.

Okay I see now. And thanks for the diagram 🙂

How about we do something like this to support both cases?

self.should_include_tag(&head_commit, &commit)? || topo_order

[braineo]

those features are independent from each other. My change only affects "what" commits are chosen, while leaving "how" they are sorted untouched.

Okay I see now. And thanks for the diagram 🙂

How about we do something like this to support both cases?

self.should_include_tag(&head_commit, &commit)? || topo_order

@orhun maybe i don't fully understand the purpose of topo_order, it seems when not specified, it uses whatever order git2 returns for the tags.

it would be useful for any chosen set of the tags. with the suggested change, in order to use topo_order one must include all the tags in the changelog.

maybe you mean some configuration like filter_tags=false?

[orhun]

it seems when not specified, it uses whatever order git2 returns for the tags.

Yeah, the tags are sorted by date as default.

with the suggested change, in order to use topo_order one must include all the tags in the changelog.

That's correct, we simply disable this new should_include_tag functionality with the code that I suggested above, since they work as expected together.

maybe you mean some configuration like filter_tags=false?

Do you mean adding a new configuration option?

[braineo]

with the suggested change, in order to use topo_order one must include all the tags in the changelog.

That's correct, we simply disable this new should_include_tag functionality with the code that I suggested above, since they work as expected together.

maybe you mean some configuration like filter_tags=false?

Do you mean adding a new configuration option

yes. i would suggest adding another option to toggle the tag filtering explicitly. because in the case when the tags are filtered, it is also desired to use the topo order but not the chronicle order. i still think filtering the tags and sorting the tags are independent from each other. with the suggested change, we will find two cases not available in the function matrix.

	filter tags	not filter tags
topo order	❌	⭕
chronicle order	⭕	❌

[braineo]

@orhun by separating the sort and filter option. it should be easier to add new sorting method like sort by semver version number etc. wdyt?

[orhun]

yes. i would suggest adding another option to toggle the tag filtering explicitly

yeah, I think that's the most sensible thing to do for supporting both use cases at this point.

by separating the sort and filter option. it should be easier to add new sorting method like sort by semver version number etc. wdyt?

Do you mean something like:

sort_tags = "topo"
sort_tags = "date" # or chronically
sort_tags = "semver"

[braineo]

@orhun ok i added a new flag to opt-in.

Do you mean something like:

sort_tags = "topo"
sort_tags = "date" # or chronically
sort_tags = "semver"

yes, if in the future there are more options added to sorting, the change should not be breaking the tag filtering.

[braineo]

hi @orhun

what do you think of the latest changes?

[orhun]

LGTM, thanks for the contribution & bearing with me :)

Applied some nitpicks and approved!