Migration guide for deprecating `textScaleFactor` in favor of `TextScaler` #8903

LongCatIsLooong · 2023-06-15T22:13:49Z

Corresponds to the framework PR: flutter/flutter#128522

Presubmit checklist

This PR doesn’t contain automatically generated corrections (Grammarly or similar).
This PR follows the Google Developer Documentation Style Guidelines — for example, it doesn’t use i.e. or e.g., and it avoids I and we (first person).
This PR uses semantic line breaks of 80 characters or fewer.

sfshaza2

I know this is still in draft, but I have feedback anyway. :)

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

sfshaza2 · 2023-06-15T23:47:04Z

Oh, this PR is currently breaking the build because these two links are missing:

[Android 14 nonlinear font scaling][]
[Ensure Android 14 compatibility][]

Finally, don't forget to add this page to the index! :D

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

LongCatIsLooong · 2023-06-22T21:26:05Z

I think this is ready for review now that the framework PR is LGTM'd. One thing that I might not have conveyed clearly in this migration guide is that the framework PR in fact doesn't add Android 14 non-linear text scaling support (it will be added in a follow up PR). So if people want to test their apps against Android 14 nonlinear text scaling then they would have to wait for a different PR to land. Do you have any suggestions on how I should add that information to the migration guide?

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

goderbauer · 2023-06-26T20:00:19Z

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

+| `SelectableText.rich({ double? TextScaleFactor = 1.0 })` constructor argument | 'textScaleFactor' is deprecated and shouldn't be used. |
+| `SelectableText.textScaleFactor` getter                                       | 'textScaleFactor' is deprecated and shouldn't be used. |
+
+## Migration guide


since non-linear text scaling isn't actually implemented I would focus the guide just on the change from textScaleFactor to textScaler and what app developers need to do to adapt to that. (In the context section it is good to mention the non-linear scaling as motivation for the change, but we shouldn't leave the impression that that's already implemented and shouldn't ask people to test it)

goderbauer · 2023-06-26T20:01:16Z

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

+consider replacing `textScaleFactor` with `TextScaler.textScaleFactor` first. The 
+`TextScaler.textScaleFactor` getter was added for backward compatibility during 
+the migration process and is expected to have a longer lifetime than other 
+`textScaleFactor` deprecations. 


I don't think we should promise a longer deprecation period. The regular policy applies here (for now).

goderbauer · 2023-06-26T20:01:56Z

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

+    // For now, implementers can still access the `textScaleFactor`.
+    // scalar via textScaler.textScaleFactor. 


Let's focus the guide on what the right way to migrate is, e.g. how should textScaler be used correctly?

Ideally, this guide shouldn't mention textScaler.textScaleFactor at all since that is not the right way to migrate your code long-term. If necessary, we can at the very end mention it for completeness, but it I wouldn't focus the guide this much around it. It's not a long-term solution and asking people to migrate to something that is already deprecated is somewhat frustrating.

Should I add a section for apps that don't target Android 14 and tell them to add an extension?

Is that realistic for an app to not target Android 14? That'll have to happen sooner or later, no? I don't think I would spend too much time on how to do the thing we don't want developers to do...

that's true for desktop-only apps or web-only apps I think?

lol, ok. The long-term goal is that TextScaler is the only text scaling mechanism in Flutter, though. And I don't think we should (pretend to) support anything else. The migration guide should show people how to migrate to TextScaler, which is the API we want people to use and the only one we will actually support in the future.

I'll save that for the migration guide for nonlinear text scaling

Co-authored-by: Michael Goderbauer <goderbauer@google.com>

sfshaza2

I have some minor updates but, overall, this looks good. @goderbauer, it seems like your issues are addressed? Is this lgtm for you?

sfshaza2 · 2023-06-27T19:36:18Z

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

+
+## Timeline
+
+Landed in version: xxx<br>


I can't land this PR until the "Landed in" field is filled out.

I'm planning to land the PR probably early next week.

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

goderbauer

LGTM

goderbauer · 2023-06-27T19:58:23Z

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

+
+The `scale` method should be used to scale font sizes in lieu of `textScaleFactor`.
+The `textScaleFactor` getter provides an estimated `textScaleFactor` value, it 
+is for backward compatibility purposes and is already marked as deprecated.


Maybe add to be very explicit: It will be removed in a future version of Flutter.

I thought it was discouraged to use future tenses in migration guides? Not sure how best to phrase this @sfshaza2 any suggestions?

That use is fine, @LongCatIsLooong.

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

goderbauer · 2023-06-27T20:01:17Z

src/release/breaking-changes/android-14-nonlinear-text-scaling.md

+```
+
+
+If the API that provides `textScaleFactor` hasn't been migrated, consider 


Basically move this before the "bad" migration advice above. (Or better: just remove that "bad" advice)

…r-text-scaling

sfshaza2 · 2023-07-05T20:24:41Z

OK! Just ping me.

LongCatIsLooong · 2023-07-17T17:59:51Z

Hi @sfshaza2 the PR is now merged. I added a section at the end of the migration guide to explain how to opt-out of non-linear scaling, since some customers wanted to QA the migration and slowly roll out.

sfshaza2 · 2023-07-18T16:22:34Z

src/release/breaking-changes/deprecate-textscalefactor.md

+
+## Timeline
+
+Landed in version: xxx<br>


Can you fill in this field?

sfshaza2

lgtm!

sfshaza2 · 2023-07-19T01:56:16Z

The build failed. Do you use API that's not yet available? If so, can you use the master channel API link?

LongCatIsLooong · 2023-07-19T02:42:56Z

Reran the test and it's passing now.

LongCatIsLooong added 3 commits June 13, 2023 01:20

API changes for Android 14 nonlinear text scaling

abfa8e9

wording

de76e2b

docs

2ae79da

sfshaza2 reviewed Jun 15, 2023

View reviewed changes

LongCatIsLooong and others added 3 commits June 15, 2023 17:00

Apply suggestions from code review

bca578b

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

attempts to fix links

793d2aa

Merge branch 'flutter:main' into android-14-nonlinear-text-scaling

16cb980

LongCatIsLooong force-pushed the android-14-nonlinear-text-scaling branch from d85b467 to 1b86a28 Compare June 22, 2023 19:47

update index.md

46d6ce3

LongCatIsLooong force-pushed the android-14-nonlinear-text-scaling branch from 1b86a28 to 46d6ce3 Compare June 22, 2023 19:51

LongCatIsLooong marked this pull request as ready for review June 22, 2023 21:20

LongCatIsLooong requested review from atsansone and parlough as code owners June 22, 2023 21:20

atsansone added the review.copy Awaiting Copy Review label Jun 23, 2023

atsansone assigned sfshaza2 Jun 23, 2023

LongCatIsLooong mentioned this pull request Jun 26, 2023

Replaces textScaleFactor with TextScaler flutter/flutter#128522

Merged

LongCatIsLooong requested a review from sfshaza2 June 26, 2023 18:16

goderbauer reviewed Jun 26, 2023

View reviewed changes

LongCatIsLooong and others added 3 commits June 26, 2023 13:09

Update src/release/breaking-changes/android-14-nonlinear-text-scaling.md

04b85e5

Co-authored-by: Michael Goderbauer <goderbauer@google.com>

Merge branch 'flutter:main' into android-14-nonlinear-text-scaling

6b67db6

review

a98c972

LongCatIsLooong changed the title ~~Migration guide for Android 14 nonlinear text scaling~~ Migration guide for deprecating textScaleFactor in favor of TextScaler Jun 26, 2023

sfshaza2 reviewed Jun 27, 2023

View reviewed changes

Apply suggestions from code review

bc6fcf5

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

goderbauer reviewed Jun 27, 2023

View reviewed changes

Merge remote-tracking branch 'origin/master' into android-14-nonlinea…

52e4399

…r-text-scaling

sfshaza2 removed the review.copy Awaiting Copy Review label Jul 10, 2023

LongCatIsLooong added 2 commits July 12, 2023 14:24

Merge branch 'flutter:main' into android-14-nonlinear-text-scaling

05fefc6

rename file. Add an example for opt-out of non-linear scaling

e6affff

atsansone added the act.await-dev-pr Needs dev PR to merge before merging docs label Jul 13, 2023

sfshaza2 reviewed Jul 18, 2023

View reviewed changes

LongCatIsLooong added 2 commits July 18, 2023 09:53

Update deprecate-textscalefactor.md

ffd8ec3

Merge branch 'main' into android-14-nonlinear-text-scaling

ba994e7

sfshaza2 approved these changes Jul 19, 2023

View reviewed changes

sfshaza2 removed the act.await-dev-pr Needs dev PR to merge before merging docs label Jul 19, 2023

sfshaza2 merged commit 5ecc8a0 into flutter:main Jul 24, 2023

LongCatIsLooong deleted the android-14-nonlinear-text-scaling branch July 24, 2023 17:28

		// For now, implementers can still access the `textScaleFactor`.
		// scalar via textScaler.textScaleFactor.

		```


		If the API that provides `textScaleFactor` hasn't been migrated, consider

Migration guide for deprecating textScaleFactor in favor of TextScaler #8903

Migration guide for deprecating textScaleFactor in favor of TextScaler #8903

Uh oh!

Conversation

LongCatIsLooong commented Jun 15, 2023

Presubmit checklist

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sfshaza2 commented Jun 15, 2023 • edited by parlough Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LongCatIsLooong commented Jun 22, 2023

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LongCatIsLooong Jun 27, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

goderbauer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfshaza2 commented Jul 5, 2023

Uh oh!

LongCatIsLooong commented Jul 17, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Migration guide for deprecating `textScaleFactor` in favor of `TextScaler` #8903

Migration guide for deprecating `textScaleFactor` in favor of `TextScaler` #8903

sfshaza2 commented Jun 15, 2023 •

edited by parlough

Loading

LongCatIsLooong Jun 27, 2023 •

edited

Loading

LongCatIsLooong commented Jul 19, 2023 •

edited

Loading