Its more complex issue Simon if you think long-term :-) This is about API, build process, project structure, and all related stuff, kind of "long-term-self-compatibility".
Basically API is: function name, parameters (names, order, types), return type, and what function does. As long as function name remains the same, it takes the same input parameters, produces the same results based on the same input (aka input-output-vectors), the API is preserved. Internal code may change, some fixes may be added, maybe additional functionality with additional input parameters combination, but the old input "vectors" giving the same output "vectors", plus the new ones, this is okay. So it is possible to build future-proof API. When we change any of the above: function name, input parameters (names, order, types), return type / data, or what function does that does not match previous behavior, then we break the API and this is called "breaking change" (it breaks existing API thus the name). In perfect world we should have all functions listed somewhere, with all their API described and numbered. We also should provide functional tests to make sure functions behave correctly for all possible valid and invalid input "vectors" that return known predictable output "vectors". But there are too many functions out there and we focus mostly on adding / fixing functionalities. Maybe we will add these one day. There are several approaches to this problem already being implemented (i.e. apps/testing/*). Breaking changes are unavoidable when for instance we want to add new features like new encryption for wifi, or new bluetooth stack version support, or change IPC kernel handling, etc, because that will most likely break existing API (well it should not but usually it does). Another example is recent MTD/FLT rewrite that improves performance and lowers memory use significantly, so it is desired change and improvement, but it breaks existing API. NuttX is used in various commercial products, including industrial ones, so any change in API, project structure, build process, etc, in any place should be clearly marked as "breaking change", because someones code may not build or worse it will build but then behave different way than before the change was made, and that may result in physical, legal, and financial damages. We heard many complains on the list about breaking changes being not marked / handled properly. I also know personally people who based their products (some years ago before I even heard about this project) sold in hundreds thousands that went away from NuttX because it was too hard to maintain, some wrote their own RTOS from scratch as an alternative. This lost trust is really hard to regain. And this hurts me personally as it impacts my projects too (i.e. people do not want to choose NuttX for upcoming projects). This is where I do not agree with Alan, there is nothing "negative" or "wrong impression" on marking breaking changes. Quite the opposite marking breaking changes clearly is a sign of maturity, because you know what to expect, even if this costs some tiny additional work, as opposed to wasting time to many different unexpected situations that you even don't know about so you even cannot predict time cost after update. I am old enough to know that "better is enemy of good". I think innovation is bringing new things without destroying the old things. But sometimes its unavoidable (for many reasons) and I get it. It is better to spend a bit more time on start to make future-proof design than flip everything upside down whenever new idea comes to mind. No one have time to track all those bazillions of changes anymore when clients expect results in days or weeks, or you will loose customers / money / reputation, and you will only have a toy to play in a free time, and we don't really have much free time left. I do agree though that "[BREAKING]" tag may be too long and "!" can be better. I am not sure if we really need to follow all relatively young "standards". I like that 99% of the community agreed that breaking changes needs better addressing. I will still insist to mark all breaking changes, both in git commits and PR titles. I really think this is "positive" and gives "good impression" on the project, and this will underline "maturity" and build "trust". Alan often references Linux or Zephyr. I don't use them anymore, quite the opposite I avoid them. I use BSD and NuttX because of all reasons mentioned above, they provide stable self-compatible working environment, and that comes after over 25 years of experience where all new "modern" projects are long gone vanished. We do not need to compete in amount of changes metrics race, we need to offer stable flexible functional and predictable working environment that can be trusted, and that will attract specific sort of people, others will find different short-life-span projects more attractive, just as with anything else :-) I really hope that we can work out together a solution that will satisfy everyone and most of all bring benefit to the project :-) Have a good day folks :-) Tomek On Mon, Aug 11, 2025 at 7:32 PM Simon Filgis <si...@ingenieurbuero-filgis.de.invalid> wrote: > > Why do we need braking changes. > > The only argument I read is: same function name, but not same function. > > Anything else? > > -- > Hard- and Softwaredevelopment Consultant > > Geschäftsführung: Simon Filgis > USt-IdNr.: DE305343278 > ISO9001:2015 <https://activities.ingenieurbuero-filgis.de/certifications> > > Tomek CEDRO <to...@cedro.info> schrieb am Mo., 11. Aug. 2025, 18:55: > > > > > https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with-both--and-breaking-change-footer > > says: > > > > """ > > Commit message with both ! and BREAKING CHANGE footer > > > > chore!: drop support for Node 6 > > > > BREAKING CHANGE: use JavaScript features not available in Node 6. > > """ > > > > + we also require "Signed-off-by:" commit footer which is not part of > > the Conventional Commits standard :-P > > > > I like Alin's idea best to put "!" as first character in git commit > > and PR title this is the simplest possible marking no matter what goes > > after and its easiest to parse :-) Maybe we should update Conventional > > Commits? :D > > > > Thanks :-) > > Tomek > > > > > > > > > > > > > > On Mon, Aug 11, 2025 at 1:59 PM Alan C. Assis <acas...@gmail.com> wrote: > > > > > > Hi Tomek, > > > > > > Yes, I agree! We could require "!" in the title and "BREAKING CHANGE: " > > in > > > the git commit message. > > > > > > Although the conventional commits spec suggest one or other I think it > > > makes sense to have both to make things clear. > > > > > > BR, > > > > > > Alan > > > > > > On Sun, Aug 10, 2025 at 7:30 PM Tomek CEDRO <to...@cedro.info> wrote: > > > > > > > The real problem here is that breaking changes were passed unmarked :-( > > > > > > > > We can change marking no problem, but we need some sort of mark both > > > > in git commit topic and PR title, do you agree Alan? > > > > > > > > Tomek > > > > > > > > On Sun, Aug 10, 2025 at 3:50 PM Alan C. Assis <acas...@gmail.com> > > wrote: > > > > > > > > > > Hi Tomek, > > > > > > > > > > It is not hiding the breaking change, it just avoids using it in the > > > > commit > > > > > title for the reasons I explained before. > > > > > > > > > > It is better to follow what other open-source projects do (like Linux > > > > > kernel, Zephyr, etc) instead of creating something that is unique to > > our > > > > > project and that could confuse users. > > > > > > > > > > If there is a standardized way to define "BREAKING CHANGE: " let's > > follow > > > > > it. > > > > > > > > > > I think there is a good reason why nobody is using "[BREAKING]" in > > the > > > > git > > > > > commit title these three months. > > > > > So, let's avoid adding it to the commit title, let's follow > > > > > the conventional commits! > > > > > > > > > > BR, > > > > > > > > > > Alan > > > > > > > > > > On Sat, Aug 9, 2025 at 6:45 PM Tomek CEDRO <to...@cedro.info> wrote: > > > > > > > > > > > On Sat, Aug 9, 2025 at 11:10 PM Tomek CEDRO <to...@cedro.info> > > wrote: > > > > > > > > > > > > > > On Sat, Aug 9, 2025 at 9:47 PM Alan C. Assis <acas...@gmail.com> > > > > wrote: > > > > > > > > > > > > > > > > Hi Everyone, > > > > > > > > > > > > > > > > I'm proposing to modify the item 1.13.9 from our > > CONTRIBUTING.md to > > > > > > avoid > > > > > > > > including the prefix "[BREAKING]" in the commit title for the > > > > following > > > > > > > > reasons: > > > > > > > > > > > > > > > > * 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/ > > > > > > > > > > > > > > > > So, please verify the suggested modification here: > > > > > > > > https://github.com/apache/nuttx/pull/16823 > > > > > > > > > > > > > > > > The suggestion as defined by conventional commits is to > > include the > > > > > > > > "BREAKING CHANGE: " in the commit log message (foot). > > > > > > > > > > > > > > Thanks Alan, but I don't agree. We have this 1.13.9 requirement > > for > > > > > > > over 3 months and it seems to be ignored on purpose :-( This came > > > > > > > after long discussions and voting. Now we want to discard that? > > > > > > > > > > > > > > Are there +1 points given for standard commit and -10 points > > taken > > > > for > > > > > > > breaking change commit anywhere? > > > > > > > > > > > > > > We _must_ clearly mark breaking changes. These cannot be hidden. > > > > > > > People will leave project if we don't. > > > > > > > > > > > > > > There is no "wrong message" or nothing "negative" in [BREAKING] > > mark. > > > > > > > You can say the same about "!" mark and "BREAKING CHANGE" in the > > > > > > > commit body. This is about API not hearts. It clearly points to a > > > > > > > change that will break people code. We should avoid breaking > > changes, > > > > > > > but when they happen these should be clearly visible and easy to > > find > > > > > > > in git log and PRs/changelogs (changelog is built from pr topic > > so pr > > > > > > > topic must contain some sort of breaking change mark). Github > > "tag" > > > > is > > > > > > > not enough because after you fetch the code you will not see > > that tag > > > > > > > in the git log. > > > > > > > > > > > > > > People will get wrong impression when they base their project and > > > > > > > instead two days of work they have to spend 2 weeks or months and > > > > then > > > > > > > after update noting works. If we clearly mark breaking changes > > they > > > > > > > will quickly know how to fix things and the trust preserves. > > Trust is > > > > > > > more important than impression. People will get wrong impression > > if > > > > we > > > > > > > hide breaking changes on purpose. > > > > > > > > > > > > > > Conventional Commits version 1.0 is around one year old. Are > > there > > > > > > > tools / projects who adopted them widely? Is this world standard? > > > > > > > > > > > > > > We do have requirements for commit messages. [BREAKING] is really > > > > > > > simple and self-explanatory. If you think only about cosmetics by > > > > > > > replacing "[BREAKING]" tag with "!:" and "BREAKING CHANGE" then > > if > > > > the > > > > > > > community prefers this one then okay. But we should mark both git > > > > > > > commit and PR topic that way so things are coherent both in git > > logs > > > > > > > and pr / changelogs and for sure we must not hide breaking > > changes in > > > > > > > any possible way. > > > > > > > > > > > > Btw this discussion started in > > > > https://github.com/apache/nuttx/pull/16793 > > > > > > where: > > > > > > 1. one function is deleted. > > > > > > 2. another function is renamed to the first function. > > > > > > 3. thus we are clearly breaking API by replacing existing function > > > > > > with different parameters, functionality, and code inside. > > > > > > > > > > > > I know this change makes some things simpler without loosing > > > > > > functionality and may be desired. I am okay with that. But other > > > > > > people also reported it as breaking. I am not okay with avoiding > > clear > > > > > > mark that someone's code will break after some change. > > > > > > > > > > > > Hiding [BREAKING] or that new "!" mark from git logs and pr / > > > > > > changelog is a deliberate hide of breaking changes, just as is not > > > > > > following the Contribution Guide. > > > > > > > > > > > > I do not understand why you guys want to hide breaking changes so > > > > > > much? Just as other FTL related changes were not marked as > > breaking. I > > > > > > just don't get it, its like shooting yourself in the foot :-( > > > > > > > > > > > > Is only amount of whatever change that matters nowadays? > > > > > > > > > > > > -- > > > > > > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info > > > > > > > > > > > > > > > > > > > > > > -- > > > > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info > > > > > > > > > > > > -- > > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info > > -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
