feat(context): add release commit range

[jdrst]

Description

Adds the used commit_range for each release.
commit_range includes the full length commit ids (commit_range.from and commit_range.to) and the short ids (commit_range.from_short and commit_range.to_short)
Also added related docs (and documentation for the sort_commits default)

Motivation and Context

See #1041

How Has This Been Tested?

Via integration_test and three new fixtures.

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.

/edit: added a third fixture. no more caveats + documentation and rustfmt/clippy

[welcome]

Thanks for opening this pull request! Please check out our contributing guidelines! ⛰️

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 40.00000% with 9 lines in your changes missing coverage. Please review.

Project coverage is 41.08%. Comparing base (aec41be) to head (1b8ecf8).

Files with missing lines	Patch %	Lines
git-cliff/src/lib.rs	0.00%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1123      +/-   ##
==========================================
- Coverage   41.09%   41.08%   -0.00%     
==========================================
  Files          21       22       +1     
  Lines        1845     1860      +15     
==========================================
+ Hits          758      764       +6     
- Misses       1087     1096       +9     

Flag	Coverage Δ
unit-tests	41.08% <40.00%> (-<0.01%)	⬇️

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.

[jdrst]

working on it :D

[jdrst]

i am unsure how to fix that timeout. is this flaky?

[orhun]

That links check should be fine... I'll take care of it later

[orhun]

Thanks for the implementation!

I had some comments and ideas :)

[orhun]

I'm thinking maybe we can remove the short variants... the templating can be used to trim them anyways.

e.g.

{{ commit_range.to | truncate(length=7, end="") }}

Also I have another idea which might change the whole implementation but... maybe adding this to the commit object would be cleaner?

e.g.

{{ commit.range.to | truncate(length=7, end="") }}

What do you think?

[jdrst]

I'm thinking maybe we can remove the short variants... the templating can be used to trim them anyways.

Short ids aren't necessarily unique when just truncated. I'd consider using the actual short id coming from git as more robust.

Also I have another idea which might change the whole implementation but... maybe adding this to the commit object would be cleaner?

I'm not sure i can follow? The commit has no idea about a range, or does it? Or do you mean, instead of having the range on the release, have it on every commit in the release? I think i'd consider that counterintuitive.

[orhun]

Oh yeah sorry, my bad. I was a bit confused there. It definitely does not belong to commit object :)

[orhun]

Short ids aren't necessarily unique when just truncated. I'd consider using the actual short id coming from git as more robust.

I'd like to double down on this though... We don't have 2 variants (short, long) in the commit object itself and it might lead to inconsistencies (in very rare cases) if we go with short-long here. So I'd prefer we only go with the long variant here.

Thoughts?

[jdrst]

I'd also like to double down :D (one last try).
What kind of inconsistencies?
I'd rather change e.g. the commit in the context to be an object with long+short (that'd be breaking though).

[orhun]

What kind of inconsistencies?

You know, we'll be supporting short hashes in one variable (commit_range) but not for the other (commit) which is not great.

The reason why I don't like supporting short commit hashes is because 7 characters is not long enough and it's more probable that two entirely different commits might belong to the same short hash.

Even worse, you can override the first 7 digits of a commit hash with a tool like lucky-commit:

$ git log
1f6383a Some commit

$ lucky_commit

$ git log
0000000 Some commit

So you can have a repo with all 000000 ids, see this git history.

[jdrst]

You know, we'll be supporting short hashes in one variable (commit_range) but not for the other (commit) which is not great.

That i absolutely understand, hence my proposition to also add it to the commit itself. But one could also argue that commit and commit_range are different use cases with different needs.

The reason why I don't like supporting short commit hashes is because 7 characters is not long enough and it's more probable that two entirely different commits might belong to the same short hash.

That is exactly my point, just from a different perspective :D. This PR does make use of git_object_short_id to circumvent that (see here)

Sorry for being so persistent. You can just put your foot down and say "Please remove the short id"!

[Cyclonit]

I'll try playing tie-breaker ;)

I'd remove the short variants too. We are talking about configuration here. I don't see a point in ommitting a few bytes here. Putting in the long hash doesn't hurt and is more expressive.

Having only one set simplifies both the code and the documentation too.

[orhun]

We need to rebase on main and fix conflicts 😊