Skip to content

Prefer TabBarTheme normalization migration guide #160018

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
rydmike opened this issue Dec 10, 2024 · 9 comments
Closed

Prefer TabBarTheme normalization migration guide #160018

rydmike opened this issue Dec 10, 2024 · 9 comments
Assignees
@QuncCccccc
Labels
f: material design flutter/packages/flutter/material repository. f: theming Styling widgets with a theme found in release: 3.27 Found to occur in 3.27 framework flutter/packages/flutter repository. See also f: labels. has reproducible steps The issue has been confirmed reproducible and is ready to work on P2 Important issues not at the top of the work list r: solved Issue is closed as solved team-design Owned by Design Languages team triaged-design Triaged by Design Languages team

Comments

@rydmike
Copy link
Contributor

rydmike commented Dec 10, 2024 •
edited
Loading

Steps to reproduce

Create a TabBarTheme instance with type declaration.

// Current TabBarTheme API in stable channel version: 3.24.5
final TabBarTheme tabTheme = Theme.of(context).tabBarTheme;

Expected results

Expect the current API usage to compile on beta/master channels OR expect the API to be documented as a totally breaking none compiling change in the coming breaking not-yet-released changes lists here: https://docs.flutter.dev/release/breaking-changes#not-yet-released-to-stable

Actual results

Using

// Current TabBar API in stable channel version: 3.24.5
final TabBarTheme tabTheme = Theme.of(context).tabBarTheme;

on beta channel version 3.27.0-0.2.pre or master 3.27.0-1.0.pre.763 the line does not compile.

There is no documentation (yet) about the coming breaking changes that causes this API to break in a manner that does not even compile.

Related PR #156253

To compile the line on beta channel version 3.27.0-0.2.pre or master 3.27.0-1.0.pre.763 you have to use:

// New TabBar API in latest beta channel version: 3.27.0-0.2.pre and
// master channel version: 3.27.0-1.0.pre.763
final TabBarThemeData tabTheme = Theme.of(context).tabBarTheme;

The change is a part of "normalizing" component theme efforts, but the none compiling breaking change needs to be documented before it is released, which is expected to happen soon. This is just a friendly reminder to document the breaking change! 😃

Code sample

Code sample 
import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      debugShowCheckedModeBanner: false,
      home: HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});
  @override
  Widget build(BuildContext context) {
    // Current TabBar API in stable channel version: 3.24.5
    final TabBarTheme tabTheme = Theme.of(context).tabBarTheme;
    // The above current API in stable is broken in beta and master,
    // meaning in coming next stable, it will not even compile!

    // New TabBarTheme API in latest beta channel version: 3.27.0-0.2.pre and
    // master channel version: 3.27.0-1.0.pre.763
    // final TabBarThemeData tabTheme = Theme.of(context).tabBarTheme;

    // Expect to find information about the TabBarThemeData class in the
    // Flutter documentation about coming none compiling breaking changes!
    // https://docs.flutter.dev/release/breaking-changes

    return Scaffold(
      appBar: AppBar(title: const Text('Home screen')),
      body: const Center(child: Text('Just some text')),
    );
  }
}

Flutter Doctor output

Doctor output 
[✓] Flutter (Channel master, 3.27.0-1.0.pre.763, on macOS 15.1.1 24B91 darwin-arm64, locale en-US)
    • Flutter version 3.27.0-1.0.pre.763 on channel master at /Users/rydmike/fvm/versions/master
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision 0104a81f55 (4 hours ago), 2024-12-10 00:31:10 -0500
    • Engine revision 0338d1c7d7
    • Dart version 3.7.0 (build 3.7.0-226.0.dev)
    • DevTools version 2.41.0

[✓] Android toolchain - develop for Android devices (Android SDK version 34.0.0)
    • Android SDK at /Users/rydmike/Library/Android/sdk
    • Platform android-34, build-tools 34.0.0
    • Java binary at: /Applications/Android Studio.app/Contents/jbr/Contents/Home/bin/java
      This is the JDK bundled with the latest Android Studio installation on this machine.
      To manually set the JDK path, use: `flutter config --jdk-dir="path/to/jdk"`.
    • Java version OpenJDK Runtime Environment (build 17.0.9+0-17.0.9b1087.7-11185874)
    • All Android licenses accepted.

[✓] Xcode - develop for iOS and macOS (Xcode 16.1)
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Build 16B40
    • CocoaPods version 1.16.2

[✓] Chrome - develop for the web
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Android Studio (version 2023.2)
    • Android Studio at /Applications/Android Studio.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 17.0.9+0-17.0.9b1087.7-11185874)

[✓] IntelliJ IDEA Community Edition (version 2024.2.5)
    • IntelliJ at /Applications/IntelliJ IDEA CE.app
    • Flutter plugin version 83.0.3
    • Dart plugin version 242.24931

[✓] VS Code (version 1.95.3)
    • VS Code at /Applications/Visual Studio Code.app/Contents
    • Flutter extension version 3.102.0

[✓] Connected device (4 available)
    • Pixel 7 Pro (mobile)            • 28131FDH300NJG        • android-arm64  • Android 15 (API 35)
    • macOS (desktop)                 • macos                 • darwin-arm64   • macOS 15.1.1 24B91 darwin-arm64
    • Mac Designed for iPad (desktop) • mac-designed-for-ipad • darwin         • macOS 15.1.1 24B91 darwin-arm64
    • Chrome (web)                    • chrome                • web-javascript • Google Chrome 131.0.6778.109
    ! Error: Browsing on the local area network for iPhone. Ensure the device is unlocked and attached with a cable or associated with the same local area
      network as this Mac.
      The device must be opted into Developer Mode to connect wirelessly. (code -27)
    ! Error: Browsing on the local area network for hype’s iPhone. Ensure the device is unlocked and attached with a cable or associated with the same local
      area network as this Mac.
      The device must be opted into Developer Mode to connect wirelessly. (code -27)
    ! Error: Browsing on the local area network for MrPinkPro. Ensure the device is unlocked and attached with a cable or associated with the same local area
      network as this Mac.
      The device must be opted into Developer Mode to connect wirelessly. (code -27)

[✓] Network resources
    • All expected network resources are available.
@danagbemava-nc danagbemava-nc added the in triage Presently being triaged by the triage team label Dec 10, 2024
@danagbemava-nc
Copy link
Member

Reproducible using the steps outlined above.

cc @QuncCccccc

flutter doctor -v 
[✓] Flutter (Channel stable, 3.24.5, on macOS 15.1.1 24B91 darwin-arm64, locale en-US)
    • Flutter version 3.24.5 on channel stable at /Users/deanli/dev/stable
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision dec2ee5c1f (4 weeks ago), 2024-11-13 11:13:06 -0800
    • Engine revision a18df97ca5
    • Dart version 3.5.4
    • DevTools version 2.37.3

[!] Flutter (Channel beta, 3.27.0-0.2.pre, on macOS 15.1.1 24B91 darwin-arm64, locale en-US)
    • Flutter version 3.27.0-0.2.pre on channel beta at /Users/deanli/dev/beta
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision fc011960a2 (4 weeks ago), 2024-11-14 12:19:18 -0800
    • Engine revision 397deba30f
    • Dart version 3.6.0 (build 3.6.0-334.4.beta)
    • DevTools version 2.40.1

[!] Flutter (Channel master, 3.27.0-1.0.pre.763, on macOS 15.1.1 24B91 darwin-arm64, locale en-US)
    • Flutter version 3.27.0-1.0.pre.763 on channel master at /Users/deanli/dev/master
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision 0104a81f55 (5 hours ago), 2024-12-10 00:31:10 -0500
    • Engine revision 0338d1c7d7
    • Dart version 3.7.0 (build 3.7.0-226.0.dev)
    • DevTools version 2.41.0

@danagbemava-nc danagbemava-nc added framework flutter/packages/flutter repository. See also f: labels. f: material design flutter/packages/flutter/material repository. has reproducible steps The issue has been confirmed reproducible and is ready to work on team-design Owned by Design Languages team found in release: 3.27 Found to occur in 3.27 and removed in triage Presently being triaged by the triage team labels Dec 10, 2024
@rydmike rydmike mentioned this issue Dec 11, 2024
Closed
@Piinks
Copy link
Contributor

Piinks commented Dec 11, 2024

cc @QuncCccccc

@Piinks Piinks added P2 Important issues not at the top of the work list triaged-design Triaged by Design Languages team f: theming Styling widgets with a theme labels Dec 11, 2024
@rydmike
Copy link
Contributor Author

rydmike commented Dec 11, 2024

This undocumented none-compiling breaking change is now live. As expected it broke the build after upgrading to 3.27.0. It is still also not mentioned in the released breaking changes.
https://docs.flutter.dev/release/breaking-changes#released-in-flutter-3-27 Update coming soon I guess 😉

@QuncCccccc QuncCccccc self-assigned this Dec 11, 2024
@Piinks
Copy link
Contributor

Piinks commented Dec 11, 2024

undocumented none-compiling breaking change

This is not the case @rydmike please review our breaking change policy. https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#handling-breaking-changes

This change was found to be non breaking, and is part of ongoing work to normalize material themes.
Updating TabBarTheme typing to TabBarThemeData is also not a difficult migration.
As always, you are welcome to submit tests to the flutter/tests directory for us to run changes against.

@Piinks Piinks changed the title Undocumented not compiling breaking change with TabBarTheme in beta and master channels Prefer TabBarTheme normalization migration guide Dec 11, 2024
@rydmike
Copy link
Contributor Author

rydmike commented Dec 11, 2024

If a past existing Flutter API does not even compile after upgrading, it is pretty hard broken, regardless of what the policy definition of a breaking change says.

Sure it is an easy fix, and yes it is part of the normalization, I'm well aware, but it still breaks the build. Thus API is hard broken 🤷🏻‍♂️ 😃

@loic-sharma

This comment was marked as resolved.

Sign in to view
@alefwd
Copy link

alefwd commented Dec 12, 2024 •
edited
Loading

undocumented none-compiling breaking change

This is not the case @rydmike please review our breaking change policy. https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#handling-breaking-changes

This change was found to be non breaking, and is part of ongoing work to normalize material themes. Updating TabBarTheme typing to TabBarThemeData is also not a difficult migration. As always, you are welcome to submit tests to the flutter/tests directory for us to run changes against.

@Piinks in the link you referenced, I read:

A breaking change is one that breaks the tests in the flutter/tests repo, and those need a migration guide

so by this definition if I have in the SDK:

int calc(int a, int b) => a + b;

and then it gets changed to:

int calc(int a, int b, int multiplier) => (a + b) * multiplier;

but if it's not tested, you wouldn't call this a breaking change. Right?

@rydmike
Copy link
Contributor Author

rydmike commented Dec 12, 2024

In this case two test files and 86 lines with the breaking change API were modified to keep the existing tests working. Many of the these test changes use and modify the exact explicit typing I used in this report to demo the broken API. See https://github.com/flutter/flutter/pull/156253/files

It is a needed breaking change to achieve the targeted API consistence for component themes.
This is fine and understandable, never claimed it was not. I do however think it is not totally unreasonable to expect such a breaking change to be documented here
https://docs.flutter.dev/release/breaking-changes#released-in-flutter-3-27

@Piinks
Copy link
Contributor

Piinks commented Dec 12, 2024

We understand the current policy is not satisfying to all users’ expectations.

We’ve actually been working on drafting new policies for breaking changes, deprecations and flutter/tests over the last few months.

Until those updates roll out though, I am not going to fault any contributor for following our policies as they are currently documented and enforced.

As for this particular issue, it was in fact documented in the release blog, please see the section on “Normalizing Material Theming”. OP also consulted on the issue. I can’t help but wonder why DialogTheme and CardTheme, which were also changed in the same way, have not been subjected to the same level of scrutiny.

Regardless, we have created a migration guide for this change in flutter/website#11489, which should soon be available on the breaking change section of the website. Please see that guide for help in updating your code.

PS - I did not write our current policy on breaking changes, I’d ask that folks not attack the messenger here and refer to our code of conduct. Thnx!

Expected results
Expect the current API usage to compile on beta/master channels OR expect the API to be documented as a totally breaking none compiling change in the coming breaking not-yet-released changes lists here: https://docs.flutter.dev/release/breaking-changes#not-yet-released-to-stable

Closing as resolved by flutter/website#11489.

@Piinks Piinks closed this as completed Dec 12, 2024
@flutter flutter locked as resolved and limited conversation to collaborators Dec 12, 2024
@danagbemava-nc danagbemava-nc added the r: solved Issue is closed as solved label Dec 13, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@QuncCccccc QuncCccccc

Labels
f: material design flutter/packages/flutter/material repository. f: theming Styling widgets with a theme found in release: 3.27 Found to occur in 3.27 framework flutter/packages/flutter repository. See also f: labels. has reproducible steps The issue has been confirmed reproducible and is ready to work on P2 Important issues not at the top of the work list r: solved Issue is closed as solved team-design Owned by Design Languages team triaged-design Triaged by Design Languages team
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@loic-sharma @Piinks @QuncCccccc @rydmike @danagbemava-nc @alefwd
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy