diff --git a/.github/labeler.yml b/.github/labeler.yml index 048292c47ea4..3eb20d8eedde 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -188,8 +188,14 @@ team-release: - any-glob-to-any-file: - docs/releases/**/* +team-tool: + - changed-files: + - any-glob-to-any-file: + - docs/tool/**/* + tool: - changed-files: - any-glob-to-any-file: - packages/flutter_tools/**/* - packages/fuchsia_remote_debug_protocol/**/* + - docs/tool/**/* diff --git a/dev/bots/analyze.dart b/dev/bots/analyze.dart index 98f39e3f5479..d33d33b31d54 100644 --- a/dev/bots/analyze.dart +++ b/dev/bots/analyze.dart @@ -1308,6 +1308,7 @@ Future verifyRepositoryLinks(String workingDirectory) async { 'chromium/chromium', 'clojure/clojure', 'dart-lang/test', // TODO(guidezpl): remove when https://github.com/dart-lang/test/issues/2209 is closed + 'dart-lang/webdev', 'eseidelGoogle/bezier_perf', 'flutter/devtools', // TODO(guidezpl): remove when https://github.com/flutter/devtools/issues/7551 is closed 'flutter/flutter_gallery_assets', // TODO(guidezpl): remove when subtask in https://github.com/flutter/flutter/issues/121564 is complete diff --git a/docs/unsorted_wiki/Updating-dependencies-in-Flutter.md b/docs/infra/Updating-dependencies-in-Flutter.md similarity index 100% rename from docs/unsorted_wiki/Updating-dependencies-in-Flutter.md rename to docs/infra/Updating-dependencies-in-Flutter.md diff --git a/docs/unsorted_wiki/Fast-Start.md b/docs/tool/Fast-Start.md similarity index 100% rename from docs/unsorted_wiki/Fast-Start.md rename to docs/tool/Fast-Start.md diff --git a/docs/unsorted_wiki/Managing-template-image-assets.md b/docs/tool/Managing-template-image-assets.md similarity index 84% rename from docs/unsorted_wiki/Managing-template-image-assets.md rename to docs/tool/Managing-template-image-assets.md index 989807308fb5..c8769b9a0dcc 100644 --- a/docs/unsorted_wiki/Managing-template-image-assets.md +++ b/docs/tool/Managing-template-image-assets.md @@ -1,3 +1,5 @@ +# Managing template image assets + Image assets used in templates in the `flutter` tool are maintained in the [flutter_template_images][fti_pkg] package on [Pub.dev][pub] and are not checked into the main [flutter/flutter][flutter_repo] repository. Flutter's presubmit checks prevent binaries from being checked in to the repository. Binary files add significant size to the repository and produce large diffs when updated. This negatively impacts Flutter users when running `flutter upgrade`. Downloading a pub package does not involve a full sync of the git history, and is therefore significantly lighter weight. @@ -15,7 +17,7 @@ First, add the images to the flutter_template_images package: 1. Fork the [flutter/packages][packages_repo] repo on GitHub. 2. Add the images at the relevant path under the `templates` directory. Filenames should be the exact final filenames as they will appear in a project generated by the `flutter` tool. They should _not_ include a `.img.tmpl` suffix. 3. Update the version in [`pubspec.yaml`](https://github.com/flutter/packages/blob/main/packages/flutter_template_images/pubspec.yaml). For new assets, increment the _minor_ version in the `major.minor.patch` version number; for updates to existing assets, increment the _patch_ version. -4. Add new heading for this version in [`CHANGELOG.md`](https://github.com/flutter/packages/blob/main/packages/flutter_template_images/CHANGELOG.md) and add a line describing your change. Follow the [Changelog Style][changelog_style] guidelines. +4. Add new heading for this version in [`CHANGELOG.md`](https://github.com/flutter/packages/blob/main/packages/flutter_template_images/CHANGELOG.md) and add a line describing your change. Follow the [Changelog Style](../ecosystem/contributing/README.md#changelog-style) guidelines. 5. Commit your changes and send a pull request. 6. Once your changes are landed, a post-submit job will automatically publish the new version on Pub. You can verify this has occurred under the _Versions_ tab of the [flutter_template_images][fti_pkg] page. @@ -24,10 +26,10 @@ First, add the images to the flutter_template_images package: Once the updated package has been published on Pub, roll your changes into the main Flutter repository. 1. Fork the [flutter/flutter][flutter_repo] repo on GitHub. -2. Edit [`packages/flutter_tools/lib/src/commands/update_packages.dart`](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/commands/update_packages.dart) and update the pinned version number for the `flutter_template_images` to the new version. +2. Edit [`packages/flutter_tools/lib/src/commands/update_packages.dart`](https://github.com/flutter/flutter/blob/main/packages/flutter_tools/lib/src/commands/update_packages.dart) and update the pinned version number for the `flutter_template_images` to the new version. 3. From within the repo directory, run `flutter update-packages --force-upgrade`. 4. For each image that you added to `flutter_template_images`, add a zero-byte file with a `.img.tmpl` suffix in the corresponding location under the [`templates`][tools_templates_dir] directory of the `flutter_tools` package. -5. Edit [`packages/flutter_tools/templates/template_manifest.json`](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/templates/template_manifest.json) and add an entry for each file you added, including the `.img.tmpl` suffix. +5. Edit [`packages/flutter_tools/templates/template_manifest.json`](https://github.com/flutter/flutter/blob/main/packages/flutter_tools/templates/template_manifest.json) and add an entry for each file you added, including the `.img.tmpl` suffix. 6. Commit your changes, and perform a test run to be sure they're emitted successfully by the `flutter` tool. 7. Assuming everything looks good, send a pull request. @@ -39,6 +41,5 @@ _(This page is referenced by an error message in the Flutter presubmit checks.)_ [flutter_repo]: https://github.com/flutter/flutter [packages_repo]: https://github.com/flutter/packages [package_templates_dir]: https://github.com/flutter/packages/tree/main/packages/flutter_template_images/templates -[tools_templates_dir]: https://github.com/flutter/flutter/tree/master/packages/flutter_tools/templates -[tools_repo]: https://github.com/flutter/flutter/tree/master/packages/flutter_tools -[changelog_style]: https://github.com/flutter/flutter/wiki/Contributing-to-Plugins-and-Packages#changelog-style \ No newline at end of file +[tools_templates_dir]: https://github.com/flutter/flutter/tree/main/packages/flutter_tools/templates +[tools_repo]: https://github.com/flutter/flutter/tree/main/packages/flutter_tools diff --git a/docs/unsorted_wiki/The-flutter-tool.md b/docs/tool/README.md similarity index 94% rename from docs/unsorted_wiki/The-flutter-tool.md rename to docs/tool/README.md index 9667fab252a0..3870cde18ea0 100644 --- a/docs/unsorted_wiki/The-flutter-tool.md +++ b/docs/tool/README.md @@ -1,3 +1,5 @@ +# The `flutter` tool + The `flutter` command-line tool is how developers (or IDEs on behalf of developers) interact with Flutter. @@ -10,7 +12,7 @@ These include: - `flutter update-packages`, which downloads all the Dart dependencies for all Dart packages in the Flutter repository. -- `flutter analyze --flutter-repo`, as described on [[Using the Dart analyzer]]. +- `flutter analyze --flutter-repo`, as described on [Using the Dart analyzer](../contributing/Using-the-Dart-analyzer.md). When contributing to Flutter, use `git pull --rebase` or `git rebase upstream/main` rather than `flutter upgrade`. @@ -21,12 +23,12 @@ you run `git pull --rebase` (or `flutter upgrade`, or anything that changes the ## Documentation The rest of this document assumes that `flutter` and `dart` on your path resolve -to the scripts inside [`/path/to/flutter/bin`](https://github.com/flutter/flutter/tree/master/bin). If either `flutter` or `dart` +to the scripts inside [`/path/to/flutter/bin`](https://github.com/flutter/flutter/tree/main/bin). If either `flutter` or `dart` on your path resolves to another binary, you should either prepend the Flutter SDK `bin` dir to the _front_ of your `$PATH`, or ensure each invocation uses the path to the Flutter SDK controlled `flutter` and `dart` binaries. -Markdown documentation can be found for some commands in [flutter/packages/flutter_tools/doc/](https://github.com/flutter/flutter/tree/master/packages/flutter_tools/doc). +Markdown documentation can be found for some commands in [flutter/packages/flutter_tools/doc/](https://github.com/flutter/flutter/tree/main/packages/flutter_tools/doc). ## Analysis @@ -102,7 +104,7 @@ The following `launch.json` config will allow you to debug the Flutter tool: Note that: -1. The current workspace directory is assumed to be the [root of the flutter_tools package](https://github.com/flutter/flutter/tree/master/packages/flutter_tools). +1. The current workspace directory is assumed to be the [root of the flutter_tools package](https://github.com/flutter/flutter/tree/main/packages/flutter_tools). 2. Update `args` to be whatever arguments you want passed to the tool (i.e. which sub-command you want to debug). 3. To debug the `flutter` command-line tool while running a `flutter` project, add `cwd` to the configuration with the path of the project. @@ -206,7 +208,7 @@ Similar to the [dwds debugging workflow](https://github.com/dart-lang/webdev/blo Each dependency we add to Flutter and the Flutter Tool makes the repo more difficult to update and requires additional work from our clients to update. -Only packages which are developed by the Dart and/or Flutter teams should be permitted into the Flutter Tool. Any third party packages that are currently in use are exempt for historical reasons, but their versions must be pinned in [update_packages.dart](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/commands/update_packages.dart#L23) . These packages should only be updated after a human review of the new version. If a Dart and/or Flutter team package depends transitively on an un-maintained or unknown package, we should work with the owners to remove or replace that transitive dependency. +Only packages which are developed by the Dart and/or Flutter teams should be permitted into the Flutter Tool. Any third party packages that are currently in use are exempt for historical reasons, but their versions must be pinned in [update_packages.dart](https://github.com/flutter/flutter/blob/main/packages/flutter_tools/lib/src/commands/update_packages.dart#L23) . These packages should only be updated after a human review of the new version. If a Dart and/or Flutter team package depends transitively on an un-maintained or unknown package, we should work with the owners to remove or replace that transitive dependency. Instead of adding a new package, ask yourself the following questions: diff --git a/docs/unsorted_wiki/The-flutter-run-variants.md b/docs/tool/The-flutter-run-variants.md similarity index 88% rename from docs/unsorted_wiki/The-flutter-run-variants.md rename to docs/tool/The-flutter-run-variants.md index b5b0a41ab6d4..6ac500441ab7 100644 --- a/docs/unsorted_wiki/The-flutter-run-variants.md +++ b/docs/tool/The-flutter-run-variants.md @@ -1,3 +1,5 @@ +# The `flutter run` variants + We aspire to reach a state where `flutter run` has the following modes: - `flutter run`: builds a debug version of the app and starts it in "hot reload" mode, then shows the console UI to manipulate the running instance. @@ -5,7 +7,7 @@ We aspire to reach a state where `flutter run` has the following modes: - `flutter run --profile`: builds a profile version of the app and starts it directly, then shows the console UI to manipulate the running instance. - `flutter run --release`: builds a release version of the app and starts it directly, then shows the console UI to manipulate the running instance. -Adding `--machine` in any of the situations above spawns a [flutter daemon](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/doc/daemon.md#flutter-run---machine) which: +Adding `--machine` in any of the situations above spawns a [flutter daemon](https://github.com/flutter/flutter/blob/main/packages/flutter_tools/doc/daemon.md#flutter-run---machine) which: * changes the output to JSON so that it can be more easily consumed by IDEs, and * allows the use of JSON commands to interact with the running application (e.g. stopping the application). diff --git a/docs/unsorted_wiki/Using-custom-embedders-with-the-Flutter-CLI.md b/docs/tool/Using-custom-embedders-with-the-Flutter-CLI.md similarity index 98% rename from docs/unsorted_wiki/Using-custom-embedders-with-the-Flutter-CLI.md rename to docs/tool/Using-custom-embedders-with-the-Flutter-CLI.md index 55c661c50a20..23095e785df1 100644 --- a/docs/unsorted_wiki/Using-custom-embedders-with-the-Flutter-CLI.md +++ b/docs/tool/Using-custom-embedders-with-the-Flutter-CLI.md @@ -1,3 +1,5 @@ +# Using custom embedders with the Flutter CLI + ## Making the Flutter CLI work with custom or third-party embedders The experimental "custom device" feature of the Flutter CLI allows you to make custom or third-party embedders such as [flutter-pi](https://github.com/ardera/flutter-pi) or the [sony embedder](https://github.com/sony/flutter-embedded-linux) work with the Flutter CLI and use features such as hot-reload, hot-restart, debugging and DevTools. Profile/release mode and plugins are not supported right now.