• Thanks @acassis, since requirement for marking breaking changes is part of Contributing Guide for 3 months but everyone seems to ignore marking, maybe other way will work.
• There is nothing wrong in [BREAKING] mark, no bad message, quite opposite, someone who finds their code broken after update will easily find possible cause that way.
• I do insist to mark breaking changes in git commit topic and PR message title as this is first place to search (git log search and changelog).
• Putting "BREAKING CHANGE" in the git commit message may be okay, but we also need this "!" mark before ":" as stated in https://www.conventionalcommits.org/en/v1.0.0/.

We also need "!" mark before ":" in the git commit topic for breaking changes as stated by [1]. Otherwise we are hiding breaking changes and this is not the goal, these should be clearly visible.

[1] https://www.conventionalcommits.org/en/v1.0.0/

• Thanks @acassis, since requirement for marking breaking changes is part of Contributing Guide for 3 months but everyone seems to ignore marking, maybe other way will work.

  • There is nothing wrong in [BREAKING] mark, no bad message, quite opposite, someone who finds their code broken after update will easily find possible cause that way.

  • I do insist to mark breaking changes in git commit topic and PR message title as this is first place to search (git log search and changelog).

@cederom the issues are those I submitted to the mailing list:

• It passes a wrong message, as something very negative (not all breaking are bad, or shouldn't be)
• Someone reading our git history could get a wrong impression of the project
• It will cluttering the title, by convention the title should have only 50 chars
• It doesn't follow the conventional commits specification: https://www.conventionalcommits.org/en/v1.0.0/

* Putting "BREAKING CHANGE" in the git commit message may be okay, but we also need this "!" mark before ":" as stated in https://www.conventionalcommits.org/en/v1.0.0/.

It is not mandatory: please see items 12 and 13 of specification. If "!" is included in the commit title the "BREAKING CHANGE: " in the foot are not required. Just it! :-)

@acassis: It is not mandatory: please see items 12 and 13 of specification. If "!" is included in the commit title the "BREAKING CHANGE: " in the foot are not required. Just it! :-)

I am for placing both "!:" in the git commit title and "BREAKING CHANGE" mark in the git commit body. "!:" is not self-explanatory, but if someone sees two git commits in the logs with both "!:" and "BREAKING CHANGE" they will quickly associate.

We cannot hide breaking changes, these must be clearly exposed and easy to find. People with broken code will search for 1. git log, 2. changelog based on PR titles, so both git commits and PR titles should follow.

This "BREAKING CHANGE: blah blah" part in the footer with description is a bit awkward because upper part of commit message already contains description what was changed and why. Thus only BREAKING CHANGE mark seems necessary if someone git --grep based on "!:" or "BREAKING" string and if someone does not yet know what the "!" in topic means.

@acassis: It is not mandatory: please see items 12 and 13 of specification. If "!" is included in the commit title the "BREAKING CHANGE: " in the foot are not required. Just it! :-)

I am for placing both "!:" in the git commit title and "BREAKING CHANGE" mark in the git commit body. "!:" is not self-explanatory, but if someone sees two git commits in the logs with both "!:" and "BREAKING CHANGE" they will quickly associate.

We cannot hide breaking changes, these must be clearly exposed and easy to find. People with broken code will search for 1. git log, 2. changelog based on PR titles, so both git commits and PR titles should follow.

This "BREAKING CHANGE: blah blah" part in the footer with description is a bit awkward because upper part of commit message already contains description what was changed and why. Thus only BREAKING CHANGE mark seems necessary if someone git --grep based on "!:" or "BREAKING" string and if someone does not yet know what the "!" in topic means.

@cederom the commit message normally says what was done, the message after "BREAKING CHANGE: " will give a hint to user how a feature was used in the past and how it is used now.

The breaking features is not supposed to be hidden, but they we don't need to be in the title :)

Could you modify the git commit message template file in this repository to also remind contributors at commit time to mark the breaking change?

.gitmessage

Update from the mailing list: @jerpelea proposes to use ! (exclamation mark) as the first character of git commit topic and PR title for breaking changes.

I like the idea best as it is most versatile no matter what comes after, costs only single char, and its easy to parse.

But it does not fully align with Conventional Commits spec.. and so we may propose that idea over there? :-)

I also agree that "BREAKING CHANGE" should be put somewhere in the git commit message and PR description, just in case someone does not know what the "!" means, or parses logs by "BREAKING" string. If we want to put this in the footer as Conventional Commits declares, then a short sentence on how to fix should follow (i.e. BREAKING CHANGE: lvgl api changed from 8 to 9, update your code.).

@acassis how Release Notes are generated? These are generated from Pull Requests right?

Thus we need this mark both in git commit and pull request. I am asking for this like 20 times already :D

Thus my proposition for the point 9:

9. Breaking Changes must be clearly marked both in Git Commits and Pull Requests: 1. Put ! (exclamation mark) as first character of the title; 2. Put BREAKING CHANGE: in the body with a brief change description and the quick-fix instructions. This helps users identify areas that need an update on their side, grep git logs, and auto-generate Release Notes.

@cederom @linguini1 please re-review and remove the change request

@acassis how Release Notes are generated?

It doesn't change the way we already generate it (BTW I never generate it, so your question should be redirected to @jerpelea :-D ). Later on we can modify the existing script to automatically detect the "!" and warn that the commit is a breaking change.

@acassis how Release Notes are generated?

It doesn't change the way we already generate it (BTW I never generate it, so your question should be redirected to @jerpelea :-D ). Later on we can modify the existing script to automatically detect the "!" and warn that the commit is a breaking change.

@jerpelea can you please explain, looks like I cannot :-)

hi @cederom If I'm not mistaken, @jerpelea uses this tool in Python.

https://github.com/apache/nuttx/blob/master/tools/doreleasenotes.py

If you want to remove breaking mark ("!") from PR titles and leave only in git commits then I will follow the community voice. Should we vote that change on the mailing list?

If you want to remove breaking mark ("!") from PR titles and leave only in git commits then I will follow the community voice. Should we vote that change on the mailing list?

Nobody is proposing it Tomek! The exclamation mark will be needed by the Release Notes script...

Could you please look at the code Luke! https://github.com/apache/nuttx/pull/16823/files

If you want to remove breaking mark ("!") from PR titles and leave only in git commits then I will follow the community voice. Should we vote that change on the mailing list?

Nobody is proposing it Tomek! The exclamation mark will be needed by the Release Notes script...

Could you please look at the code Luke! https://github.com/apache/nuttx/pull/16823/files

Release Notes are generated from Pull Requests not git commits:

• See https://nuttx.apache.org/releases/12.10.0/.
• Note the list contains links to Pull Request URL on GitHub. You can click a number before change title and you are redirected to a Pull Request.
• See the RN generation script https://github.com/apache/nuttx/blob/master/tools/doreleasenotes.py, the commit is only used to obtain date not the title.

1. Original requirement text - there is git commit and PR title:

9. Breaking Change must be clearly marked with a [BREAKING] tag in the
   git commit topic and PR title that will propagate to Release Notes.

2. New requirement proposition - no PR title here just git commit:

Breaking change must be clearly identified with inclusion of an
exclamation mark ! as the first character of the commit title and a
BREAKING CHANGE: in the git commit log message, followed by a short
comment about how the user should adapt their code. This change
description will be used to create the Release Notes.

3. My proposition - both git commit and PR title as before change:

Breaking Changes must be clearly marked both in Git Commits and Pull Requests: 1. Put ! (exclamation mark) as first character of the title; 2. Put BREAKING CHANGE: in the body with a brief change description and the quick-fix instructions. This helps users identify areas that need an update on their side, grep git logs, and auto-generate Release Notes.

This "!" (+"BREAKING CHANGE:") mark should be both part of Git Commit and the Pull Request too as this tells more attention needed here when checking, and it aligns with existing release process as explained above. This is my last message about this.

Let @jerpelea decide he is the Release Manager :-)

@cederom a PR could contains more than one commit, and more than one commit can break different things. Currently we don't track Break Changes, so the script will need to be updated anyway. Then we modify it to detect breaks on commit instead of PR

BTW, looking at https://github.com/apache/nuttx/blob/master/tools/doreleasenotes.py seems like it go by commits, not PR

@linguini1 please review, I already fixed the suggest.

@cederom please review and remove Change Request since the modification as implemented as suggested and adding it to PR too as you later suggested is redundant.

@jerpelea ?

Ok @jerpelea, let us to discuss there, but I think there is no way to prevent people to create a PR with more than one commit. And some cases it is necessary to have more than one commit to avoid compilation errors (when you modify and driver and need to modify the board files).

You cannot include the board modifications in the driver commit and you cannot separate it in a new PR otherwise the driver PR will break the board building.