Is there an existing issue for this?

• I have searched the existing issues
• I have read the guide to filing a bug

Use case

Currently, when changes are considered breaking changes are defined in the Wiki (emphasis mine):

Implement the change you wish to see and run the existing tests against your new code (without having changed the tests first). Changes that break (i.e. require changes to) one or more of the contributed tests are considered "breaking changes".

In cases where these tests pass but we can nonetheless imagine reasonable scenarios where developers would be affected negatively, by courtesy, once the change has landed, engineers are encouraged to announce the changes by sending an e-mail to flutter-announce@, a message to the #announcements channel on our Chat, and tagging the relevant issues with the c: API break label (such that they will be included in our release notes). However, we do not consider these breaking changes.

According to this definition, there can be changes that break existing code but are not listed in the Breaking changes section of the release note.
And, actually there are.

Example

After upgrading to Flutter 3.13 yesterday, my production code had completely broken.

I had very hard time debugging the issue and finally found the cause was the breaking PR #128082, which changes the behavior of ExpansionPanelList, after taking a few hours to follow this path:

1. Notice the code has been broken.

2. Visit the Breaking changes section of the release note to find there are no related announcement.

3. Visit the official doc of ExpansionPanelList to identify its source code is located at flutter/packages/flutter/lib/src/material/expansion_panel.dart.

4. git clone this repository.

5. git log -p expansion_panel.dart to show the logs of all of the commits which change the implementation of ExpansionListPanel.

6. Reading the logs, I found the related PR above.

Proposal

The current definition of breaking changes are extremely counter-intuitive.
A change which easily breaks existing codes (like in the example above) aren't necessarily considered breaking changes, and thus are not listed in the list of breaking changes in the release note.

There are two proposals:

1. Please change the definition of breaking changes in a more intuitive way. Considering every change which breaks existing codes a breaking change is one good idea, I think.

2. Plus, optionally, every breaking change can be explicitly noted in the official documentation. For example, in the case of ExpansionPanelList above, there can be a statement like this:

   ⚠️ The value of isExpanded flag passed to expansionCallback had been changed in Flutter 3.13. See #128082 for the details.

Side Note

There is a related issue: Please notify us all breaking changes when releasing new stable. #37771. This is locked as resolved but it is NOT resolved at all.