Add example PRs to git-cliff-readme-example for label-based changelog testing

[ognis1205]

Hi everyone 👋

To help test features like the one introduced in orhun/git-cliff#1163 more smoothly, I’d like to propose adding a few PRs with various labels to the git-cliff-readme-example repository.

This could serve as a sandbox for validating label-based changelog generation and help contributors understand how different labels affect the output.

Would it be okay to start adding some example PRs to that repository for this purpose?
Happy to coordinate if needed!

Thanks 🙌

[orhun]

Hey!

Sure, that sounds reasonable. What kind of a commit/PR do you have in mind for adding there?

[ognis1205]

Hey @orhun , thanks!

For the commit/PR examples, I think it would be great to include at least the four basic combinations:

• Conventional commit with label
• Conventional commit without label
• Unconventional commit with label
• Unconventional commit without label

Also, it would be ideal if the examples align with the commit parsers shown in the git-cliff docs. Specifically, I’d love to see examples that reflect all of the label patterns demonstrated in this snippet:

commit_parsers = [
  { field = "github.pr_labels", pattern = "breaking-change", group = "<!-- 0 --> 🏗️ Breaking changes" },
  { field = "github.pr_labels", pattern = "type/enhancement", group = "<!-- 1 --> 🚀 Features" },
  { field = "github.pr_labels", pattern = "type/bug", group = "<!-- 2 --> 🐛 Fixes" },
  { field = "github.pr_labels", pattern = "type/update", group = "<!-- 3 --> 🧪 Dependencies" },
  { field = "github.pr_labels", pattern = "type/refactor", group = "<!-- 4 --> 🏭 Refactor" },
  { field = "github.pr_labels", pattern = "area/documentation", group = "<!-- 5 --> 📝 Documentation" },
  { field = "github.pr_labels", pattern = ".*", group = "<!-- 6 --> 🌀 Miscellaneous" },
]

So ideally, we’d have at least one example PR title for each of the following labels:

breaking-change

• Title: feat: drop support for legacy token format
  Labels: breaking-change, type/enhancement (conventional)
• Title: Removed old token logic
  Labels: breaking-change, type/refactor (unconventional)

type/enhancement

• Title: feat: add support for GitHub Enterprise
  Labels: type/enhancement (conventional)
• Title: Support GitHub Enterprise
  Labels: type/enhancement (unconventional)

type/bug

• Title: fix: handle empty payloads in webhook parser
  Labels: type/bug (conventional)
• Title: Webhooks crash on empty body
  Labels: type/bug (unconventional)

type/update

• Title: chore(deps): bump tokio from 1.35 to 1.36
  Labels: type/update (conventional)
• Title: update tokio version
  Labels: type/update (unconventional)

type/refactor

• Title: refactor: extract label parsing logic into separate module
  Labels: type/refactor (conventional)
• Title: Split label logic out
  Labels: type/refactor (unconventional)

area/documentation

• Title: docs: clarify label matching behavior
  Labels: area/documentation (conventional)
• Title: Improve README
  Labels: area/documentation (unconventional)

If that works for you, I’d be happy to open a PR myself. WDYT?

[orhun]

Thanks for the details. For those PRs to show up in the Git history we need to merge them, which means we will eventually add new commits. Right now this list seems a bit excessive and we might have some overlap with the existing commit (types). (e.g. we have a commit like feat: add parser already which falls under the "conventional without label category".)

I propose:

• Rethink the whole commit history for the examples. Keep it minimal, maybe 10 commits, 2 releases and unreleased version.
• Overwrite the history of that repository.

For doing that, maybe it would be better to do a reverse approach where we come up with the expected changelog first and then start building the PRs/commits individually.

What do you think?

[ognis1205]

I think that approach makes sense. If it would be helpful, I can also try coming up with a possible changelog first. Let me know what you think.

[orhun]

Yes, please do :)

[ognis1205]

Hi @orhun,

Regarding the commit/PR history, I propose this one.

The goal is to validate the following configuration:

commit_parsers = [
  { field = "github.pr_labels", pattern = "breaking change", group = "🏗️ Breaking changes" },
  { field = "github.pr_labels", pattern = "type/enhancement", group = "🚀 Features" },
  { field = "github.pr_labels", pattern = "type/bug", group = "🐛 Fixes" },
  { field = "github.pr_labels", pattern = "type/update", group = "🧪 Dependencies" },
  { field = "github.pr_labels", pattern = "type/refactor", group = "🏭 Refactor" },
  { field = "github.pr_labels", pattern = "area/documentation", group = "📝 Documentation" },
  { message = ".*", group = "🌀 Miscellaneous" },
]

The expected output from git-cliff:

### <!-- 0 --> 🏗️ Breaking changes
- refactor(parser): expose string functions
- docs(example)!: add tested usage example

### <!-- 1 --> 🚀 Features
- feat(cache): use cache while fetching pages
- feat(config): support multiple file formats
- feat(parser): add ability to parse arrays

### <!-- 2 --> 🐛 Fixes
- fix(args): rename help argument due to conflict
- chore(release): add release script

### <!-- 5 --> 📝 Documentation
- docs(project): add README.md

### <!-- 6 --> 🌀 Miscellaneous
- Initial commit

The structure of PRs and the associated commits:

PR #5: Initial features

Included Commits:

• feat(cache): use cache while fetching pages
• feat(config): support multiple file formats
• feat(parser): add ability to parse arrays

Labels:

• type/enhancement

---

PR #4: Bugfix and chore

Included Commits:

• fix(args): rename help argument due to conflict
• chore(release): add release script

Labels:

• type/bug
• type/update

---

PR #3: Refactor and breaking changes

Included Commits:

• refactor(parser): expose string functions
• docs(example)!: add tested usage example

Labels:

• type/refactor
• breaking change
• area/documentation

---

PR #2: Documentation updates

Included Commits:

• docs(project): add README.md

Labels:

• area/documentation

---

PR #1: Initial commit

Included Commits:

• Initial commit

Labels:

• None

All PRs in this test repository are merged using "Rebase and merge" to keep a linear history and ensure clean commit separation.

[orhun]

I like it, it's pretty clean!

How do you want to proceed? You can either create the repo and transfer ownership to me or I can work on it

[ognis1205]

Sounds good! Since you seem to be quite busy with other things as well, I’ll go ahead and create the repo on my end and transfer ownership to you afterward. I will let you know once the repo is ready.

[ognis1205]

Hey @orhun,

I created this repository for testing a commit parser assuming PR-based development:

https://github.com/ognis1205/git-cliff-readme-example-pull-requests

I tested using it and noticed one thing. In this repository, I used "rebase and merge" for merging PRs (to keep a linear commit history). In that case, the logic implemented in this line:

git-cliff/git-cliff-core/src/remote/mod.rs

Line 353 in dc458ea

let pull_request = pull_requests.iter().find(|pr| {

works well for squash merges and similar, but with rebase merges, the PR information is only associated with the last commit in the PR — not with all the commits included in the PR.

Is this the intended behavior? Or do you think this might require a feature enhancement?

[orhun]

Ah damn, yes. That's one of the limitations that we have right now. The remote integration only takes the "merge commits" into account while populating the release entries. As a workaround, we can probably create a PR for each commit.

This should be definitely improved though!

[ognis1205]

Thanks for the reply @orhun !

Got it. For now, I’ll recreate the test repository with a one-PR-per-commit approach.
Regarding the linkage between commits and PRs — I haven’t decided on a concrete implementation strategy yet, but if it makes sense, can I file an issue for it and could you please assign me? I’d be happy to take a look.

[orhun]

Yup, sounds good! Thanks :)

[ognis1205]

Hey @orhun ,

I've created two repositories: one links multiple commits to a single PR, and the other links one commit per PR:

• https://github.com/ognis1205/git-cliff-readme-example-rebase-and-merge
• https://github.com/ognis1205/git-cliff-readme-example-one-pr-one-commit

I've submitted transfer requests for both, so please check them when you have time.

[orhun]

Looking good, thanks! I just transferred them.

I think we can now use them in fixtures 🥳

[ognis1205]

Thanks! I'll submit a PR to update the fixture later as well.

[ognis1205]

Hey @orhun ,

I submitted the PR regarding the fixture:
#1178

Please take a look when you have time!