Declare package:flutter_gen to be deprecated (#11343)

Declare the `package:flutter_gen` approach deprecated and explain the
current migration path.

Part of flutter/flutter#157819,
flutter/flutter#102983.

/cc @andrewkolos

---------

Co-authored-by: Jonah Williams <[email protected]>
Co-authored-by: Chris Bracken <[email protected]>

firebase.json

@@ -683,6 +683,7 @@
       { "source": "/to/et", "destination": "https://flutter.dev/to/engine-tool", "type": 301 },
       { "source": "/to/federated-plugins", "destination": "/packages-and-plugins/developing-packages#federated-plugins", "type": 301 },
       { "source": "/to/ffi-package", "destination": "/packages-and-plugins/developing-packages#plugin-ffi", "type": 301 },
+      { "source": "/to/flutter-gen-deprecation", "destination": "/release/breaking-changes/flutter-generate-i10n-source", "type": 301 },
       { "source": "/to/flutter-plugins-configuration", "destination": "/release/breaking-changes/flutter-plugins-configuration", "type": 301 },
       { "source": "/to/flutter-fix", "destination": "/tools/flutter-fix", "type": 301 },
       { "source": "/to/flutter-gradle-plugin-apply", "destination": "/release/breaking-changes/flutter-gradle-plugin-apply", "type": 301 },

src/content/release/breaking-changes/flutter-generate-i10n-source.md

@@ -0,0 +1,90 @@
+---
+title: Localized messages are generated into source, not a synthetic package.
+description: >-
+  When using `package:flutter_localizations`, the default generated location
+  (and eventually, only possible location) is within your source (`lib/`)
+  directory, and not the synthetic package `package:flutter_gen`.
+---
+
+## Summary
+
+The `flutter` tool will no longer generate a synthetic `package:flutter_gen`
+or modify the `package_config.json` of the application. Applications or tools
+that previously referenced `package:flutter_gen` will instead reference source
+files generated into the application directly.
+
+## Background
+
+`flutter_gen` is a virtual (synthetic) package that is created by the `flutter`
+command-line tool to allow developers to import that package to access generated
+symbols and functionality, such as for
+[internationalization][Internationalizing Flutter apps]. As the package is not
+listed in an app's `pubspec.yaml`, and is created via re-writing the (generated)
+`package_config.json`, numerous problems have been created.
+
+## Migration Guide
+
+This change only effects users that have the following in their `pubspec.yaml`:
+
+```yaml
+flutter:
+  generate: true
+```
+
+A synthetic package (`package:flutter_gen`) is created and referenced by the
+application:
+
+```dart
+import 'package:flutter_gen/gen_l10n/app_localizations.dart';
+// ...
+const MaterialApp(
+  title: 'Localizations Sample App',
+  localizationsDelegates: AppLocalizations.localizationsDelegates,
+  supportedLocales: AppLocalizations.supportedLocales,
+);
+```
+
+There are two ways to migrate away from importing `package:flutter_gen`:
+
+1. Specify `synthetic-package: false` in the accompanying [l10n.yaml][] file:
+
+    ```yaml
+    synthetic-package: false
+
+    # The files are generated into the path specified by `arb-dir`
+    arb-dir: lib/i18n
+
+    # Or, specifically provide an output path:
+    output-dir: lib/src/generated/i18n
+    ```
+
+2. Pass `--no-implicit-pubspec-resolution` to invocations of the `flutter` tool:
+
+    ```sh
+    flutter run --no-implicit-pubspec-resolution
+    ```
+
+## Timeline
+
+Not released
+
+Not released + 1, `package:flutter_gen` support will be removed.
+
+## References
+
+Relevant Issues:
+
+- [Issue 73870][], where `package:flutter_gen` pub problems are first found.
+- [Issue 102983][], where `package:flutter_gen` problems are outlined.
+- [Issue 157819][], where `--implicit-pubspec-resolution` is discussed.
+
+Relevant Articles:
+
+- [Internationalizing Flutter apps][], the canonical documentation for the
+  feature.
+
+[l10n.yaml]: https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization#configuring-the-l10n-yaml-file
+[Issue 73870]: https://github.com/flutter/flutter/issues/73870
+[Issue 102983]: https://github.com/flutter/flutter/issues/102983
+[Issue 157819]: https://github.com/flutter/flutter/issues/157819
+[Internationalizing Flutter apps]: https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization#adding-your-own-localized-messages

src/content/release/breaking-changes/flutter-plugins-configuration.md

@@ -119,10 +119,10 @@ See [Deprecated imperative apply of Flutter's Gradle plugins][imperative-apply]
 for details of switching to the newer plugin DSL.
 
 To smoke test whether your build relies on a `.flutter-plugins` file, you
-can use the flag `--no-emit-legacy-flutter-plugins`:
+can use the flag `--no-implicit-pubspec-resolution`:
 
 ```sh
-flutter build apk --no-emit-legacy-flutter-plugins
+flutter build apk --no-implicit-pubspec-resolution
 ```
 
 Any build tools or scripts that might rely on that file being output will now

src/content/release/breaking-changes/index.md

@@ -33,6 +33,7 @@ release, and listed in alphabetical order:
 
 ### Not yet released to stable
 
+* [Localized messages are generated into source, not a synthetic package][]
 * [`.flutter-plugins-dependencies` replaces `.flutter-plugins`][] <!-- Branch cut starts here, below will be in next stable -->
 * [`Color` wide gamut support][]
 * [Remove invalid parameters for `InputDecoration.collapsed`][]
@@ -41,6 +42,7 @@ release, and listed in alphabetical order:
 * [Set default for SystemUiMode to Edge-to-Edge][]
 * [Deprecate `ThemeData.dialogBackgroundColor` in favor of `DialogThemeData.backgroundColor`][]
 
+[Localized messages are generated into source, not a synthetic package]: /release/breaking-changes/flutter-generate-i10n-source
 [`.flutter-plugins-dependencies` replaces `.flutter-plugins`]: /release/breaking-changes/flutter-plugins-configuration
 [`Color` wide gamut support]: /release/breaking-changes/wide-gamut-framework
 [Remove invalid parameters for `InputDecoration.collapsed`]: /release/breaking-changes/input-decoration-collapsed