Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Definition of breaking changes should be improved. #133025

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
2 tasks done
your-diary opened this issue Aug 22, 2023 · 4 comments
Closed
2 tasks done

Definition of breaking changes should be improved. #133025

your-diary opened this issue Aug 22, 2023 · 4 comments
Labels
r: invalid Issue is closed as not valid

Comments

@your-diary
Copy link

your-diary commented Aug 22, 2023 •
edited
Loading

Is there an existing issue for this?

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.
@your-diary your-diary mentioned this issue Aug 22, 2023
Merged
@huycozy huycozy added the in triage Presently being triaged by the triage team label Aug 22, 2023
@stuartmorgan-g
Copy link
Contributor

  1. Considering every change which breaks existing codes a breaking change is one good idea, I think.

Every single change has the potential to break some existing code somewhere (including in private repositories). How do you propose determining whether any code exists anywhere that is broken by any given change?

@huycozy huycozy added the waiting for customer response The Flutter team cannot make further progress on this issue until the original reporter responds label Aug 22, 2023
@your-diary
Copy link
Author

your-diary commented Aug 22, 2023 •
edited
Loading

@stuartmorgan
That is just an idea.
What I want to say is the definition should be MORE intuitive as the current one is TOO counter-intuitive.
COMPLETE detection of every breaking change is impossible as you say, but I don't say "the definition should be COMPLETELY intuitive".

For example, if an existing API is changed or removed, the change will surely break some of existing codes.
On the other hand, when a new API is added, the probability where existing codes break is relatively small.
So defining any change of removal of an existing API as a breaking change is intuitive and will work well.
This is another idea.
(Maybe I should also say what I want to say is not "do use my idea" but "I think this should be xxx. My ideas to fix the situation are yyy and zzz. Let's discuss it.")

Looking at another community, how Go treats and announces breaking changes are better: Backward Compatibility, Go 1.21, and Go 2

I strongly believe any changes which apparently BREAK existing code shall be listed in the list of BREAKing changes.

@github-actions github-actions bot removed the waiting for customer response The Flutter team cannot make further progress on this issue until the original reporter responds label Aug 22, 2023
@stuartmorgan-g
Copy link
Contributor

stuartmorgan-g commented Aug 22, 2023 •
edited
Loading

What you are describing is essentially the previous policy. The current policy exists because that policy was impairing the ability of Flutter to evolve, and this policy was deliberately chosen to change the balance of development speed vs breakage.

This policy is being regularly evaluated against the Flutter community surveys that are run periodically, which has questions specifically tailored to this topic and the inherent tradeoffs we are aware it involves. The way it would change would be a shift in the aggregate responses to those questions, rather than individual anecdotes about specific breakage.

Given that, I'm going to close this; it doesn't cover anything that isn't already being considered regularly, and there's nothing actionable to track with an issue at the current time.

@stuartmorgan-g stuartmorgan-g closed this as not planned Won't fix, can't repro, duplicate, stale Aug 22, 2023
@huycozy huycozy added r: invalid Issue is closed as not valid and removed in triage Presently being triaged by the triage team labels Aug 22, 2023
@github-actions
Copy link

github-actions bot commented Sep 5, 2023

This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Sep 5, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
r: invalid Issue is closed as not valid
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@stuartmorgan-g @your-diary @huycozy