Conventions for commit messages

deekerman commented

2026-02-22 03:25:37 -05:00

Owner

Originally created by @sledgehammer999 on GitHub (Apr 22, 2025).

This is a continuation of a discussion started in https://github.com/qbittorrent/qBittorrent/pull/21971#issuecomment-2817859706

Purpose of this discussion: Explore ways to alleviate the changelog generation and maintenance

Proposal

Adopt Conventional Commits. It's ruleset is small and lax. It's a quick read.
There is tooling available for Convential Commits that generates changelog based on the commits.

I propose to start with very lax rules on how we write commits:

Use feat for features (supposedly these are not to be backported)
Use fix for true bugfixes that are supposed to be backported. Not for fixups of a previously unreleased state.
Fixes belonging to specific modules (rss, search, webui, webapi, os-specific, NSIS) should either have their own type defined OR use a scope for the fix type.
Don't use a type for internal refactorings or other stuff that doesn't fit the 3 above points (aka not follow the "Conventional commits" spec). OR use any other type expecting it to be ignored for the changelog.

The tooling will be used to extract a changeset solely based on the feat/fix types while ignoring all other commits.

Discussion

Discuss possible problems that may arise from the above. And/or propose a different approach (but don't make a different proposal for the sake of it).

Originally created by @sledgehammer999 on GitHub (Apr 22, 2025). This is a continuation of a discussion started in https://github.com/qbittorrent/qBittorrent/pull/21971#issuecomment-2817859706 **Purpose of this discussion:** Explore ways to alleviate the changelog generation and maintenance ### Proposal Adopt [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). It's ruleset is small and lax. It's a quick read. There is tooling available for Convential Commits that generates changelog based on the commits. I propose to start with very lax rules on how we write commits: 1. Use `feat` for features (supposedly these are not to be backported) 2. Use `fix` for true bugfixes that are supposed to be backported. Not for fixups of a previously unreleased state. 3. Fixes belonging to specific modules (rss, search, webui, webapi, os-specific, NSIS) should either have their own type defined OR use a scope for the `fix` type. 4. Don't use a type for internal refactorings or other stuff that doesn't fit the 3 above points (aka not follow the "Conventional commits" spec). OR use any other type expecting it to be ignored for the changelog. The tooling will be used to extract a changeset solely based on the `feat`/`fix` types while ignoring all other commits. ### Discussion Discuss possible problems that may arise from the above. And/or propose a different approach (but don't make a different proposal for the sake of it).

deekerman added the

Discussion

Project management

labels

2026-02-22 03:25:37 -05:00

deekerman commented

2026-02-22 03:25:41 -05:00

Author

Owner

@sledgehammer999 commented on GitHub (Apr 22, 2025):

From https://github.com/qbittorrent/qBittorrent/pull/21971#issuecomment-2820522564

These are the claims that exist right now without detailed consideration:

IIRC, CC enforces us to use "all lowercase" format of commit titles. This may not be a big problem for the commits themselves, but what will it look like if you automatically create Changelog entries from them, which are supposed to have the correct spelling?

No, CC doesn't enforce spelling or capitalization. We can choose any type and scope. All tools can be configured to recognize the types/scopes we want.
Furthermore, the tools usually have facilities that can manipulate each found entry based on its type/scope. We define that behavior. It usually passes through a template. For now, assume that the changelog can be generated in the format we currently use.

What about multi scope commits? (I hope you're not going to insist on splitting them into separate commits.)

I suppose we could use the scope that is the most relevant. Like what would be the likeliest changelog entry for this when I manually would make the entry? If many types are equally likely, just choose one.

What about commits that fix a bug as a side effect (i.e., they provide much more changes than are needed just to fix the bug)?

Same as above.

Or if the bug can be fixed only with the introduction of a new feature?

Is it a single commit? Then it probably deserves the feat type. Is it multiple commits? One of them gets the feat type, the bugfixing one gets the fix type, and the intermediate ones (if any) don't get a type.

@sledgehammer999 commented on GitHub (Apr 22, 2025): From https://github.com/qbittorrent/qBittorrent/pull/21971#issuecomment-2820522564 >These are the claims that exist right now without detailed consideration: > > IIRC, CC enforces us to use "all lowercase" format of commit titles. This may not be a big problem for the commits themselves, but what will it look like if you automatically create Changelog entries from them, which are supposed to have the correct spelling? No, CC doesn't enforce spelling or capitalization. We can choose any type and scope. All tools can be configured to recognize the types/scopes we want. Furthermore, the tools usually have facilities that can manipulate each found entry based on its type/scope. We define that behavior. It usually passes through a template. **For now**, assume that the changelog can be generated in the format we currently use. > What about multi scope commits? (I hope you're not going to insist on splitting them into separate commits.) I suppose we could use the scope that is the most relevant. Like what would be the likeliest changelog entry for this when I manually would make the entry? If many types are equally likely, just choose one. > What about commits that fix a bug as a side effect (i.e., they provide much more changes than are needed just to fix the bug)? Same as above. >Or if the bug can be fixed only with the introduction of a new feature? Is it a single commit? Then it probably deserves the `feat` type. Is it multiple commits? One of them gets the `feat` type, the bugfixing one gets the `fix` type, and the intermediate ones (if any) don't get a type.

deekerman commented

2026-02-22 03:25:43 -05:00

Author

Owner

@Chocobo1 commented on GitHub (Apr 22, 2025):

Addressing comments from https://github.com/qbittorrent/qBittorrent/pull/21971#issuecomment-2820522564

These are the claims that exist right now without detailed consideration:

1. IIRC, CC enforces us to use "all lowercase" format of commit titles. This may not be a big problem for the commits themselves, but what will it look like if you automatically create Changelog entries from them, which are supposed to have the correct spelling?

I didn't see such rule in the spec. Also we don't need to follow https://www.conventionalcommits.org/en/v1.0.0/ literally. We can go our own way it if it don't diverge from the format too much and as long as we can still benefits from the changelog generator.

2. What about multi scope commits? (I hope you're not going to insist on splitting them into separate commits.)

IMO if you need multiple entries in the changelog then create multiple git commits with each complying to the CC format. Otherwise you can use non-CC format for the commits you don't wish to be included in changelog.

@Chocobo1 commented on GitHub (Apr 22, 2025): Addressing comments from https://github.com/qbittorrent/qBittorrent/pull/21971#issuecomment-2820522564 > These are the claims that exist right now without detailed consideration: > > 1. IIRC, CC enforces us to use "all lowercase" format of commit titles. This may not be a big problem for the commits themselves, but what will it look like if you automatically create Changelog entries from them, which are supposed to have the correct spelling? I didn't see such rule in the spec. Also we don't need to follow https://www.conventionalcommits.org/en/v1.0.0/ literally. We can go our own way it if it don't diverge from the format too much and as long as we can still benefits from the changelog generator. > 2. What about multi scope commits? (I hope you're not going to insist on splitting them into separate commits.) IMO if you need multiple entries in the changelog then create multiple git commits with each complying to the CC format. Otherwise you can use non-CC format for the commits you don't wish to be included in changelog.

deekerman commented

2026-02-22 03:25:43 -05:00

Author

Owner

@sledgehammer999 commented on GitHub (Apr 22, 2025):

In the meantime we should follow what I said in https://github.com/qbittorrent/qBittorrent/pull/21971#issuecomment-2817859706

While I was compiling this changelog I had some thoughts. As glassez mentioned elsewhere, this maintenance is suboptimal and I agree. I propose a change in the approach.

I think people implementing "feature" PRs should put a changelog entry in their PR. The changelog can always be reviewed/adjusted before release. This is a soft requirement. Reviewers should request a changelog entry BUT not treat non-compliance as a blocker. I expect that the usual contributors will comply anyway. Only newcomers will be a hit or miss.

"bugfixes" PRs that get backported shouldn't concern themselves with this. The backport list for each release should be small enough to be manageable by me in a timely manner. However, if the person doing the backport wants to add changelog entries then I won't stop them. It isn't a requirement.

ALSO we should simulate this proposal on the current/new PRs and imagine how they would look like. If we identify any problems we should comment on them here as a concrete illustritative example.

@sledgehammer999 commented on GitHub (Apr 22, 2025): In the meantime we should follow what I said in https://github.com/qbittorrent/qBittorrent/pull/21971#issuecomment-2817859706 > While I was compiling this changelog I had some thoughts. As glassez mentioned elsewhere, this maintenance is suboptimal and I agree. I propose a change in the approach. > > I think people implementing "feature" PRs should put a changelog entry in their PR. The changelog can always be reviewed/adjusted before release. This is a **soft** requirement. Reviewers should request a changelog entry BUT not treat non-compliance as a blocker. I expect that the usual contributors will comply anyway. Only newcomers will be a hit or miss. > > "bugfixes" PRs that get backported shouldn't concern themselves with this. The backport list for each release should be small enough to be manageable by me in a timely manner. However, if the person doing the backport wants to add changelog entries then I won't stop them. It isn't a requirement. **ALSO** we should simulate this proposal on the current/new PRs and imagine how they would look like. If we identify any problems we should comment on them here as a concrete illustritative example.

deekerman commented

2026-02-22 03:25:43 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

We can go our own way it if it don't diverge from the format too much and as long as we can still benefits from the changelog generator.

If forgeting about CC and consider the above as a starting point, I would suggest simply adding the Changelog related information as a "special" section to the commit body (while leaving our current commit formatting rules as-is).

@glassez commented on GitHub (Apr 22, 2025): > We can go our own way it if it don't diverge from the format too much and as long as we can still benefits from the changelog generator. If forgeting about CC and consider the above as a starting point, I would suggest simply adding the Changelog related information as a "special" section to the commit body (while leaving our current commit formatting rules as-is).

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@Chocobo1 commented on GitHub (Apr 22, 2025):

To give something more concrete to discuss, here is how I would define the types and scopes:

type: [
    'Feature', # new features
    'Fix', # fixing something
    'Refactor', # Maybe consider adding this? IMO even if they not always are visible to the average users,
                # they reduce the technical debt and pave way for new features.
                # The changelog may leave it out.
    'Chore' # anything else. I reckon for consistency, everything should have its own type.
            # The changelog may leave it out.
]
scope: [
    # this list is non-exhaustive, more can be added along the way
    'Core',
    'CI',
    'Doc',
    'GUI',
    'I18n',
    'I2P',
    'NSIS',
    'RSS',
    'Search',
    'WebAPI',
    'WebUI'
]

And this is the result of a few commits on master:
Before:

WebUI: Don't update UI if the page is hidden
WebUI: migrate away from recursion calls
Bump copyright year
Sync translations from Transifex and run lupdate
WebUI: Optimize table performance with virtual list
Improve error messages
Add versioning to socks.py
Clamp seeding time limit in session
Swap add file/link buttons on toolbar
Enforce SOCKS proxy setting in search engine plugins

After:

Feature(WebUI): Don't update UI if the page is hidden
Refactor(WebUI): migrate away from recursion calls
Chore(Core): Bump copyright year
Chore(Core): Sync translations from Transifex and run lupdate
Feature(WebUI): Optimize table performance with virtual list
Refactor(Search): Improve error messages
Refactor(Search): Add versioning to socks.py
Fix(Core): Clamp seeding time limit in session
Fix(WebUI): Swap add file/link buttons on toolbar
Fix(Search): Enforce SOCKS proxy setting in search engine plugins

@Chocobo1 commented on GitHub (Apr 22, 2025): To give something more concrete to discuss, here is how I would define the types and scopes: ```yaml type: [ 'Feature', # new features 'Fix', # fixing something 'Refactor', # Maybe consider adding this? IMO even if they not always are visible to the average users, # they reduce the technical debt and pave way for new features. # The changelog may leave it out. 'Chore' # anything else. I reckon for consistency, everything should have its own type. # The changelog may leave it out. ] scope: [ # this list is non-exhaustive, more can be added along the way 'Core', 'CI', 'Doc', 'GUI', 'I18n', 'I2P', 'NSIS', 'RSS', 'Search', 'WebAPI', 'WebUI' ] ``` And this is the result of a few commits on master: Before: ``` WebUI: Don't update UI if the page is hidden WebUI: migrate away from recursion calls Bump copyright year Sync translations from Transifex and run lupdate WebUI: Optimize table performance with virtual list Improve error messages Add versioning to socks.py Clamp seeding time limit in session Swap add file/link buttons on toolbar Enforce SOCKS proxy setting in search engine plugins ``` After: ``` Feature(WebUI): Don't update UI if the page is hidden Refactor(WebUI): migrate away from recursion calls Chore(Core): Bump copyright year Chore(Core): Sync translations from Transifex and run lupdate Feature(WebUI): Optimize table performance with virtual list Refactor(Search): Improve error messages Refactor(Search): Add versioning to socks.py Fix(Core): Clamp seeding time limit in session Fix(WebUI): Swap add file/link buttons on toolbar Fix(Search): Enforce SOCKS proxy setting in search engine plugins ```

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

Ok, let's give it a try.
At least if it has a clear indication of which commits should be mentioned in the Changelog and which should not, this in itself will simplify even the manual (semi-automatic) creation of the Changelog, right?

@glassez commented on GitHub (Apr 22, 2025): Ok, let's give it a try. At least if it has a clear indication of which commits should be mentioned in the Changelog and which should not, this in itself will simplify even the manual (semi-automatic) creation of the Changelog, right?

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

@Chocobo1
How about merge commits?

@glassez commented on GitHub (Apr 22, 2025): @Chocobo1 How about merge commits?

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@sledgehammer999 commented on GitHub (Apr 22, 2025):

My 2 cents:

I don't particularly like the format "Fix(WebUI)". I would prefer straight "WebUI: blah blah". At least for fixes and features.

For more context: Currently, for anything related to WebUI I almost always put it under the WEBUI prefix in the changelog. In this case, I don't differentiate between BUGFIX and FEATURE. I use BUGFIX for any fix NOT belonging to a distinct module. Same for FEATURE.

@sledgehammer999 commented on GitHub (Apr 22, 2025): My 2 cents: I don't particularly like the format "Fix(WebUI)". I would prefer straight "WebUI: blah blah". At least for fixes and features. For more context: Currently, for anything related to WebUI I almost always put it under the `WEBUI` prefix in the changelog. In this case, I don't differentiate between `BUGFIX` and `FEATURE`. I use `BUGFIX` for any fix NOT belonging to a distinct module. Same for `FEATURE`.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

@Chocobo1
If Refactor is suggested as valid type I would use Feature instead of Feat.

@glassez commented on GitHub (Apr 22, 2025): @Chocobo1 If Refactor is suggested as valid type I would use Feature instead of Feat.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

I don't particularly like the format "Fix(WebUI)". I would prefer straight "WebUI: blah blah". At least for fixes and features.

So how do you distinguish those commits that should be mentioned in the Changelog from those that shouldn't?

Currently, for anything related to WebUI I almost always put it under the WEBUI prefix in the changelog. In this case, I don't differentiate between BUGFIX and FEATURE. I use BUGFIX for any fix NOT belonging to a distinct module. Same for FEATURE.

Maybe, on the contrary, it makes sense to revise the Changelog format too?

@glassez commented on GitHub (Apr 22, 2025): > I don't particularly like the format "Fix(WebUI)". I would prefer straight "WebUI: blah blah". At least for fixes and features. So how do you distinguish those commits that should be mentioned in the Changelog from those that shouldn't? > Currently, for anything related to WebUI I almost always put it under the `WEBUI` prefix in the changelog. In this case, I don't differentiate between `BUGFIX` and `FEATURE`. I use `BUGFIX` for any fix NOT belonging to a distinct module. Same for `FEATURE`. Maybe, on the contrary, it makes sense to revise the Changelog format too?

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

One more question. How could the automated tool exclude from the Changelog those commits that were backported to the previous branch?

@glassez commented on GitHub (Apr 22, 2025): One more question. How could the automated tool exclude from the Changelog those commits that were backported to the previous branch?

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@xavier2k6 commented on GitHub (Apr 22, 2025):

Can output be like below? as in add - after type, I think it's more readable...

Feat - (WebUI): Don't update UI if the page is hidden
Refactor - (WebUI): migrate away from recursion calls
Chore - (Core): Bump copyright year
Chore - (Core): Sync translations from Transifex and run lupdate
Feat - (WebUI): Optimize table performance with virtual list
Refactor - (Search): Improve error messages
Refactor - (Search): Add versioning to socks.py
Fix - (Core): Clamp seeding time limit in session
Fix - (WebUI): Swap add file/link buttons on toolbar
Fix - (Search): Enforce SOCKS proxy setting in search engine plugins

@xavier2k6 commented on GitHub (Apr 22, 2025): Can output be like below? as in add ` - ` after type, I think it's more readable... ``` Feat - (WebUI): Don't update UI if the page is hidden Refactor - (WebUI): migrate away from recursion calls Chore - (Core): Bump copyright year Chore - (Core): Sync translations from Transifex and run lupdate Feat - (WebUI): Optimize table performance with virtual list Refactor - (Search): Improve error messages Refactor - (Search): Add versioning to socks.py Fix - (Core): Clamp seeding time limit in session Fix - (WebUI): Swap add file/link buttons on toolbar Fix - (Search): Enforce SOCKS proxy setting in search engine plugins ```

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

Can output be like below? as in add - after type, I think it's more readable...

IMO, using in prefix both hyphens and parentheses simultaneously is an overkill. But we can just add a space between type and scope:

Feature (WebUI):

@glassez commented on GitHub (Apr 22, 2025): > Can output be like below? as in add `-` after type, I think it's more readable... IMO, using in prefix both hyphens and parentheses simultaneously is an overkill. But we can just add a space between type and scope: > Feature (WebUI):

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@thalieht commented on GitHub (Apr 22, 2025):

Will this affect the 50 char limit for commit messages?

@thalieht commented on GitHub (Apr 22, 2025): Will this affect the [50 char limit for commit messages](https://github.com/qbittorrent/qBittorrent/blob/master/CODING_GUIDELINES.md#10-git-commit-message)?

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

Will this affect the 50 char limit for commit messages?

This length was already tight enough, and given the mandatory prefixes, it will unlikely to contain enough information. I would suggest to make it equal to the maximum length that GitHub displays without cropping.

@glassez commented on GitHub (Apr 22, 2025): > Will this affect the [50 char limit for commit messages](https://github.com/qbittorrent/qBittorrent/blob/master/CODING_GUIDELINES.md#10-git-commit-message)? This length was already tight enough, and given the mandatory prefixes, it will unlikely to contain enough information. I would suggest to make it equal to the maximum length that GitHub displays without cropping.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@Chocobo1 commented on GitHub (Apr 22, 2025):

For more context: Currently, for anything related to WebUI I almost always put it under the WEBUI prefix in the changelog. In this case, I don't differentiate between BUGFIX and FEATURE. I use BUGFIX for any fix NOT belonging to a distinct module. Same for FEATURE.

It seems you are talking about the changelog, right? Then I suppose the changelog generator is able to detect WEBUI commits and put them into its own WEBUI section. And this won't affect how we write the commit title.

From https://git-cliff.org/docs/configuration/git#commit_parsers :

{ message = "^feat", group = "Features" }
Group the commit as "Features" if the commit message (description) starts with "feat".

If Refactor is suggested as valid type I would use Feature instead of Feat.

Sure.

At least if it has a clear indication of which commits should be mentioned in the Changelog and which should not, this in itself will simplify even the manual (semi-automatic) creation of the Changelog, right?

Yes. All these hurdles are about generating changelog easier and faster. For the maintainer and the contributors.

How about merge commits?

I'll prefer leave them as-is and don't apply CC to them. The changelog generator should be able to ignore them.

How could the automated tool exclude from the Changelog those commits that were backported to the previous branch?

Either manually filter them out or write some script to automate it.
From https://git-cliff.org/docs/configuration/git#commit_parsers :

{ message = "^revert", skip = true }
Skip processing the commit if the commit message (description) starts with "revert".

For example, one can use PR #NNNN to match and filter the changelog entries.

@Chocobo1 commented on GitHub (Apr 22, 2025): >For more context: Currently, for anything related to WebUI I almost always put it under the WEBUI prefix in the changelog. In this case, I don't differentiate between BUGFIX and FEATURE. I use BUGFIX for any fix NOT belonging to a distinct module. Same for FEATURE. It seems you are talking about the changelog, right? Then I suppose the changelog generator is able to detect WEBUI commits and put them into its own WEBUI section. And this won't affect how we write the commit title. From https://git-cliff.org/docs/configuration/git#commit_parsers : >{ message = "^feat", group = "Features" } >Group the commit as "Features" if the commit message (description) starts with "feat". >If Refactor is suggested as valid type I would use Feature instead of Feat. Sure. >At least if it has a clear indication of which commits should be mentioned in the Changelog and which should not, this in itself will simplify even the manual (semi-automatic) creation of the Changelog, right? Yes. All these hurdles are about generating changelog easier and faster. For the maintainer and the contributors. >How about merge commits? I'll prefer leave them as-is and don't apply CC to them. The changelog generator should be able to ignore them. >How could the automated tool exclude from the Changelog those commits that were backported to the previous branch? Either manually filter them out or write some script to automate it. From https://git-cliff.org/docs/configuration/git#commit_parsers : >{ message = "^revert", skip = true } >Skip processing the commit if the commit message (description) starts with "revert". For example, one can use `PR #NNNN` to match and filter the changelog entries.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@sledgehammer999 commented on GitHub (Apr 22, 2025):

My 2 cents:

I don't particularly like the format "Fix(WebUI)". I would prefer straight "WebUI: blah blah". At least for fixes and features.

For more context: Currently, for anything related to WebUI I almost always put it under the WEBUI prefix in the changelog. In this case, I don't differentiate between BUGFIX and FEATURE. I use BUGFIX for any fix NOT belonging to a distinct module. Same for FEATURE.

Here I am talking about cosmetics in the git log, and giving context via what I do in the changelog.
Do you like git logs that look like this:

Feat(WebUI): Don't update UI if the page is hidden
Refactor(WebUI): migrate away from recursion calls
Chore(Core): Bump copyright year
Chore(Core): Sync translations from Transifex and run lupdate
Feat(WebUI): Optimize table performance with virtual list
Refactor(Search): Improve error messages
Refactor(Search): Add versioning to socks.py
Fix(Core): Clamp seeding time limit in session
Fix(WebUI): Swap add file/link buttons on toolbar
Fix(Search): Enforce SOCKS proxy setting in search engine plugins

or like this:

WebUI: Don't update UI if the page is hidden
WebUI: migrate away from recursion calls
Chore(Core): Bump copyright year
Chore(Core): Sync translations from Transifex and run lupdate
WebUI: Optimize table performance with virtual list
Refactor(Search): Improve error messages
Refactor(Search): Add versioning to socks.py
Fix: Clamp seeding time limit in session
WebUI: Swap add file/link buttons on toolbar
Search: Enforce SOCKS proxy setting in search engine plugins

or even this (ommitting type for internal commits):

WebUI: Don't update UI if the page is hidden
WebUI: migrate away from recursion calls
Bump copyright year
Sync translations from Transifex and run lupdate
WebUI: Optimize table performance with virtual list
Improve error messages
Add versioning to socks.py
Fix: Clamp seeding time limit in session
WebUI: Swap add file/link buttons on toolbar
Search: Enforce SOCKS proxy setting in search engine plugins

Personally I like number 2 and maybe number 3.

How about merge commits?

Do you mean entries like Merge pull request #22482 from Chocobo1/process_env ? Then I suggest we leave them as-is. The tools will ignore them. They aren't needed for the changelog.

One more question. How could the automated tool exclude from the Changelog those commits that were backported to the previous branch?

AFAICT it can't. However judging from the recent stable releases it will be easy to manually filter the backported changes when creating the 1st changelog of the new major release. The number of backports isn't big and a simple search&replace should do most of the work.

Lastly, I would vote to keep Feat as it is standard term in CC.

@sledgehammer999 commented on GitHub (Apr 22, 2025): > My 2 cents: > > I don't particularly like the format "Fix(WebUI)". I would prefer straight "WebUI: blah blah". At least for fixes and features. > > For more context: Currently, for anything related to WebUI I almost always put it under the `WEBUI` prefix in the changelog. In this case, I don't differentiate between `BUGFIX` and `FEATURE`. I use `BUGFIX` for any fix NOT belonging to a distinct module. Same for `FEATURE`. Here I am talking about cosmetics in the **git** log, and giving context via what I do in the changelog. Do you like git logs that look like this: ``` Feat(WebUI): Don't update UI if the page is hidden Refactor(WebUI): migrate away from recursion calls Chore(Core): Bump copyright year Chore(Core): Sync translations from Transifex and run lupdate Feat(WebUI): Optimize table performance with virtual list Refactor(Search): Improve error messages Refactor(Search): Add versioning to socks.py Fix(Core): Clamp seeding time limit in session Fix(WebUI): Swap add file/link buttons on toolbar Fix(Search): Enforce SOCKS proxy setting in search engine plugins ``` or like this: ``` WebUI: Don't update UI if the page is hidden WebUI: migrate away from recursion calls Chore(Core): Bump copyright year Chore(Core): Sync translations from Transifex and run lupdate WebUI: Optimize table performance with virtual list Refactor(Search): Improve error messages Refactor(Search): Add versioning to socks.py Fix: Clamp seeding time limit in session WebUI: Swap add file/link buttons on toolbar Search: Enforce SOCKS proxy setting in search engine plugins ``` or even this (ommitting `type` for internal commits): ``` WebUI: Don't update UI if the page is hidden WebUI: migrate away from recursion calls Bump copyright year Sync translations from Transifex and run lupdate WebUI: Optimize table performance with virtual list Improve error messages Add versioning to socks.py Fix: Clamp seeding time limit in session WebUI: Swap add file/link buttons on toolbar Search: Enforce SOCKS proxy setting in search engine plugins ``` Personally I like number 2 and maybe number 3. >How about merge commits? Do you mean entries like `Merge pull request #22482 from Chocobo1/process_env` ? Then I suggest we leave them as-is. The tools will ignore them. They aren't needed for the changelog. >One more question. How could the automated tool exclude from the Changelog those commits that were backported to the previous branch? AFAICT it can't. However judging from the recent stable releases it will be easy to manually filter the backported changes when creating the 1st changelog of the new major release. The number of backports isn't big and a simple search&replace should do most of the work. Lastly, I would vote to keep `Feat` as it is standard term in CC.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

@sledgehammer999
As per above.
If you do not intend to have consistent commit titles, then I would prefer to leave everything as it is, and add the Changelog hints as a special field to the commit message body (as I suggested previously).

@glassez commented on GitHub (Apr 22, 2025): @sledgehammer999 As per above. If you do not intend to have consistent commit titles, then I would prefer to leave everything as it is, and add the Changelog hints as a special field to the commit message body (as I suggested previously).

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@sledgehammer999 commented on GitHub (Apr 22, 2025):

If you do not intend to have consistent commit titles

What do you mean by this? Or, better yet, how are my proposed titles inconsistent?

@sledgehammer999 commented on GitHub (Apr 22, 2025): >If you do not intend to have consistent commit titles What do you mean by this? Or, better yet, how are my proposed titles inconsistent?

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 22, 2025):

Or, better yet, how are my proposed titles inconsistent?

If commit title has a prefix, then it must belong to a single classification. For example, "Fix", "Feature", "Refactor" belong to a single classification. "Fix" and "WebUI" not.

@glassez commented on GitHub (Apr 22, 2025): > Or, better yet, how are my proposed titles inconsistent? If commit title has a prefix, then it must belong to a single classification. For example, "Fix", "Feature", "Refactor" belong to a single classification. "Fix" and "WebUI" not.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@Chocobo1 commented on GitHub (Apr 23, 2025):

Do you like git logs that look like this:

TBH, I find adding prefix ugly. But if we are going to make changes and improve things. I would prefer it has clear logic structure and uniformity so that leaves option 2 and 3 out. I would choose option 1 or its variant.

@Chocobo1 commented on GitHub (Apr 23, 2025): >Do you like git logs that look like this: TBH, I find adding prefix ugly. But if we are going to make changes and improve things. I would prefer it has clear logic structure and uniformity so that leaves option 2 and 3 out. I would choose option 1 or its [variant](https://github.com/qbittorrent/qBittorrent/issues/22595#issuecomment-2821656918).

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 23, 2025):

TBH, I find adding prefix ugly.

👍
I really dislike the way Conventional Commits do the job.

@glassez commented on GitHub (Apr 23, 2025): > TBH, I find adding prefix ugly. 👍 I really dislike the way [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) do the job.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@Chocobo1 commented on GitHub (Apr 23, 2025):

I really dislike the way Conventional Commits do the job.

And I mean all kinds of prefix. Like the current GHA CI: and WebUI: etc. But lets not delve into it.

Another idea is we utilize the commit footer (which is at the bottom of the commit body) and write some format that can help the changelog generator. This way we can keep using the usual commit title format. I have not think thoroughly about this though.

@Chocobo1 commented on GitHub (Apr 23, 2025): >I really dislike the way [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) do the job. And I mean all kinds of prefix. Like the current `GHA CI:` and `WebUI:` etc. But lets not delve into it. Another idea is we utilize the commit footer (which is at the bottom of the commit body) and write some format that can help the changelog generator. This way we can keep using the usual commit title format. I have not think thoroughly about this though.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 23, 2025):

Another idea is we utilize the commit footer (which is at the bottom of the commit body) and write some format that can help the changelog generator. This way we can keep using the usual commit title format. I have not think thoroughly about this though.

Just like I suggested above. IMO, commit body (footer) is better place for some kind of service info.

And I mean all kinds of prefix. Like the current GHA CI: and WebUI: etc.

The current prefixes were discussed and approved earlier to clearly distinguish commits that are not related to qBittorrent application itself. Otherwise, the titles of such commit would look either confusing or difficult to come up with, or too long, etc. But if you have any ideas on how to do it in another acceptable way, you're welcome (within separate Issue/PR).

@glassez commented on GitHub (Apr 23, 2025): > Another idea is we utilize the commit footer (which is at the bottom of the commit body) and write some format that can help the changelog generator. This way we can keep using the usual commit title format. I have not think thoroughly about this though. Just like I suggested above. IMO, commit body (footer) is better place for some kind of service info. > And I mean all kinds of prefix. Like the current `GHA CI:` and `WebUI:` etc. The current prefixes were discussed and approved earlier to clearly distinguish commits that are not related to qBittorrent application itself. Otherwise, the titles of such commit would look either confusing or difficult to come up with, or too long, etc. But if you have any ideas on how to do it in another acceptable way, you're welcome (within separate Issue/PR).

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@Chocobo1 commented on GitHub (Apr 23, 2025):

IMO, commit body (footer) is better place for some kind of service info.

As a start (again). Maybe still use the defines from https://github.com/qbittorrent/qBittorrent/issues/22595#issuecomment-2821018905 but put it at the footer and only use the prefix part.

For example:

WebUI: migrate away from recursion calls

some messages.
Closes #NNNN.
PR #NNNN.

Refactor (WebUI)  // for changelog generator
Refactor[WebUI]   // or another format

ps. I'm not sure but I hope the generator can be configured to support this.

@Chocobo1 commented on GitHub (Apr 23, 2025): >IMO, commit body (footer) is better place for some kind of service info. As a start (again). Maybe still use the defines from https://github.com/qbittorrent/qBittorrent/issues/22595#issuecomment-2821018905 but put it at the footer and only use the prefix part. For example: ``` WebUI: migrate away from recursion calls some messages. Closes #NNNN. PR #NNNN. Refactor (WebUI) // for changelog generator Refactor[WebUI] // or another format ``` ps. I'm not sure but I hope the generator can be configured to support this.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 23, 2025):

IMO, commit body (footer) is better place for some kind of service info.

As a start (again). Maybe still use the defines from #22595 (comment) but put it at the footer and only use the prefix part.
I'm not sure but I hope the generator can be configured to support this.

If it's going to be in commit body footer, then I don't really care what format it's going to use. This should be based more on what will be more convenient for processing by Changelog generator.

@glassez commented on GitHub (Apr 23, 2025): > > IMO, commit body (footer) is better place for some kind of service info. > > As a start (again). Maybe still use the defines from [#22595 (comment)](https://github.com/qbittorrent/qBittorrent/issues/22595#issuecomment-2821018905) but put it at the footer and only use the prefix part. > I'm not sure but I hope the generator can be configured to support this. If it's going to be in commit body footer, then I don't really care what format it's going to use. This should be based more on what will be more convenient for processing by Changelog generator.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@sledgehammer999 commented on GitHub (Apr 24, 2025):

TBH, I find adding prefix ugly.

I really dislike the way Conventional Commits do the job.

So, I guess the 3 of us don't really like CC (for different reasons each). So we should probably stop thinking about adopting CC.

Putting something in the footer/body sounds better and I almost agree. I want to raise the following POV and hear your opinion.

It seems to me that requiring a prefix in the title will be more intuitive for newcomers to follow. It will be easier to verify for reviewers, both in terms of correctness and in terms of existence.
On the other hand, a rule about a footer might be missed by a committer (even a regular one), and the reviewer might forget to check for it too.

However, it might be easy to write a CI check that checks for a footer, and posts a comment in the PR thread when missing (as a soft warning/reminder).

@sledgehammer999 commented on GitHub (Apr 24, 2025): >TBH, I find adding prefix ugly. > I really dislike the way [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) do the job. So, I guess the 3 of us don't really like CC (for different reasons each). So we should probably stop thinking about adopting CC. Putting something in the footer/body sounds better and I almost agree. I want to raise the following POV and hear your opinion. It seems to me that requiring a prefix in the title will be more intuitive for newcomers to follow. It will be easier to verify for reviewers, both in terms of correctness and in terms of existence. On the other hand, a rule about a footer might be missed by a committer (even a regular one), and the reviewer might forget to check for it too. However, it might be easy to write a CI check that checks for a footer, and posts a comment in the PR thread when missing (as a soft warning/reminder).

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 25, 2025):

It seems to me that requiring a prefix in the title will be more intuitive for newcomers to follow.

Most of the changes are made by more or less permanent members.
In addition, we are usually dealing with a more complex process than simply merging the provided commit as it is. It requires squashing several intermediate commits, editing the message, and adding references to PR and closed Issue. So the final appearance of the merged commit is the (de facto) responsibility of the member who merges it.

@glassez commented on GitHub (Apr 25, 2025): > It seems to me that requiring a prefix in the title will be more intuitive for newcomers to follow. Most of the changes are made by more or less permanent members. In addition, we are usually dealing with a more complex process than simply merging the provided commit as it is. It requires squashing several intermediate commits, editing the message, and adding references to PR and closed Issue. So the final appearance of the merged commit is the (de facto) responsibility of the member who merges it.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 25, 2025):

Refactor (WebUI) // for changelog generator
Refactor[WebUI] // or another format

To make it easier for the Changelog generator to find the appropriate part of the message body, it could start with some permanent prefix:

WebUI: migrate away from recursion calls

Some messages.
PR #NNNN.
Closes #NNNN.
 
Changelog-hints: Refactor (WebUI)

@glassez commented on GitHub (Apr 25, 2025): > Refactor (WebUI) // for changelog generator > Refactor[WebUI] // or another format To make it easier for the Changelog generator to find the appropriate part of the message body, it could start with some permanent prefix: ``` WebUI: migrate away from recursion calls Some messages. PR #NNNN. Closes #NNNN. Changelog-hints: Refactor (WebUI) ```

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@sledgehammer999 commented on GitHub (Apr 25, 2025):

It seems to me that requiring a prefix in the title will be more intuitive for newcomers to follow.

Most of the changes are made by more or less permanent members. In addition, we are usually dealing with a more complex process than simply merging the provided commit as it is. It requires squashing several intermediate commits, editing the message, and adding references to PR and closed Issue. So the final appearance of the merged commit is the (de facto) responsibility of the member who merges it.

Then I guess we should try it for a while. If it doesn't work, we scrap it.

Refactor (WebUI) // for changelog generator
Refactor[WebUI] // or another format

To make it easier for the Changelog generator to find the appropriate part of the message body, it could start with some permanent prefix:
WebUI: migrate away from recursion calls

Some messages.
PR #NNNN.
Closes #NNNN.
 
Changelog-hints: Refactor (WebUI)

Should we always require the footer? Or can it be omitted if the change is not changelog-worthy?
IMO, the person who merges (and the original author) should concern themselves with helping with the maintenance of a changelog. Not with providing context for every single commit/merge. Hence, only provide info when a changelog entry is needed.

As for the generator: We could implement a simple script ourselves. git log provides pretty formatting based on switches. The script will parse the body backwards from the end until a blank line is found (or the start is reached). This is the footer. Each line should be checked for a possible prefix eg <prefix>:<space><message>. We predefine the prefixes we care about.

@sledgehammer999 commented on GitHub (Apr 25, 2025): > > It seems to me that requiring a prefix in the title will be more intuitive for newcomers to follow. > > Most of the changes are made by more or less permanent members. In addition, we are usually dealing with a more complex process than simply merging the provided commit as it is. It requires squashing several intermediate commits, editing the message, and adding references to PR and closed Issue. So the final appearance of the merged commit is the (de facto) responsibility of the member who merges it. Then I guess we should try it for a while. If it doesn't work, we scrap it. > > Refactor (WebUI) // for changelog generator > > Refactor[WebUI] // or another format > > To make it easier for the Changelog generator to find the appropriate part of the message body, it could start with some permanent prefix: > > ``` > WebUI: migrate away from recursion calls > > Some messages. > PR #NNNN. > Closes #NNNN. > > Changelog-hints: Refactor (WebUI) > ``` Should we always require the footer? Or can it be omitted if the change is not changelog-worthy? IMO, the person who merges (and the original author) should concern themselves with helping with the maintenance of a changelog. Not with providing context for every single commit/merge. Hence, only provide info when a changelog entry is needed. As for the generator: We could implement a simple script ourselves. `git log` provides pretty formatting based on switches. The script will parse the body backwards from the end until a blank line is found (or the start is reached). This is the footer. Each line should be checked for a possible prefix eg `<prefix>:<space><message>`. We predefine the prefixes we care about.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (Apr 25, 2025):

only provide info when a changelog entry is needed.

👍

@glassez commented on GitHub (Apr 25, 2025): > only provide info when a changelog entry is needed. 👍

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@Chocobo1 commented on GitHub (May 2, 2025):

As for the generator: We could implement a simple script ourselves. git log provides pretty formatting based on switches. The script will parse the body backwards from the end until a blank line is found (or the start is reached). This is the footer. Each line should be checked for a possible prefix eg :. We predefine the prefixes we care about.

About the prefix/format, if my proposal in https://github.com/qbittorrent/qBittorrent/issues/22595#issuecomment-2824256542 wasn't good enough then someone must propose something else so we don't stall here.

@Chocobo1 commented on GitHub (May 2, 2025): >As for the generator: We could implement a simple script ourselves. git log provides pretty formatting based on switches. The script will parse the body backwards from the end until a blank line is found (or the start is reached). This is the footer. Each line should be checked for a possible prefix eg <prefix>:<space><message>. We predefine the prefixes we care about. About the prefix/format, if my proposal in https://github.com/qbittorrent/qBittorrent/issues/22595#issuecomment-2824256542 wasn't good enough then someone must propose something else so we don't stall here.

deekerman commented

2026-02-22 03:25:44 -05:00

Author

Owner

@glassez commented on GitHub (May 2, 2025):

About the prefix/format, if my proposal in #22595 (comment) wasn't good enough then someone must propose something else so we don't stall here.

I would assume that the commit body footer does not belong only to the Changelog generator. Therefore, I would use prefixes differently, i.e. so that they do not contain (only) Changelog related data, but distinguish those data from others:

WebUI: migrate away from recursion calls

some messages.
PR #NNNN.
Closes #NNNN.

Co-authored-by: @some-people
Some-other-info: foobar
Changelog-entry: Refactor (WebUI)
// or maybe even more detailed
// Changelog-entry-type: Refactor
// Changelog-entry-scope: WebUI
// Changelog-entry-title: Migrate away from recursion calls
// Changelog-entry-author: Chocobo1

@glassez commented on GitHub (May 2, 2025): > About the prefix/format, if my proposal in [#22595 (comment)](https://github.com/qbittorrent/qBittorrent/issues/22595#issuecomment-2824256542) wasn't good enough then someone must propose something else so we don't stall here. I would assume that the commit body footer does not belong only to the Changelog generator. Therefore, I would use prefixes differently, i.e. so that they do not contain (only) Changelog related data, but distinguish those data from others: ``` WebUI: migrate away from recursion calls some messages. PR #NNNN. Closes #NNNN. Co-authored-by: @some-people Some-other-info: foobar Changelog-entry: Refactor (WebUI) // or maybe even more detailed // Changelog-entry-type: Refactor // Changelog-entry-scope: WebUI // Changelog-entry-title: Migrate away from recursion calls // Changelog-entry-author: Chocobo1 ```

Rows
Columns

Conventions for commit messages #16799

Proposal

Discussion