From 22570daa18acf8785ba74707b35bbc72b10dfd63 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Tue, 24 Sep 2024 16:03:08 -0400 Subject: [PATCH] Misc docs cleanup and fixes (#155501) --- CONTRIBUTING.md | 9 +++- dev/conductor/README.md | 2 +- dev/conductor/RELEASE_ONBOARDING.md | 27 ++++++++---- dev/devicelab/README.md | 2 +- docs/Flutter-Self-Service-Index.md | 4 +- docs/In-case-of-emergency.md | 3 +- docs/README.md | 2 +- docs/about/Glossary.md | 4 +- docs/about/The-Engine-architecture.md | 4 +- docs/contributing/Chat.md | 2 +- ...p-the-Framework-development-environment.md | 4 +- .../Style-guide-for-Flutter-repo.md | 8 ++-- .../Making-animated-GIFs-of-Flutter-apps.md | 2 +- .../issue_hygiene/Popular-issues.md | 2 +- .../testing/Flutter-Test-Fonts.md | 2 + ...-a-golden-file-test-for-package-flutter.md | 6 +-- ...ugins-and-Packages-repository-structure.md | 9 ++-- docs/ecosystem/contributing/README.md | 8 ++-- ...up-the-Packages-development-environment.md | 2 +- docs/ecosystem/release/README.md | 2 +- docs/infra/Autorollers.md | 6 +-- docs/infra/Autosubmit-bot.md | 42 +++++++++++++++---- .../Flutter-Framework-Gardener-Rotation.md | 14 ++++++- ...-a-new-integration-test-to-Framework-CI.md | 4 +- docs/infra/Landing-Changes-With-Autosubmit.md | 8 +++- docs/infra/Reducing-Test-Flakiness.md | 15 ++++++- docs/infra/Rolling-Dart.md | 6 +-- docs/infra/Understanding-Google-Testing.md | 6 +-- .../infra/Updating-dependencies-in-Flutter.md | 2 +- ...ps-are-compiled-with-Gradle-for-Android.md | 2 +- docs/platforms/android/New-Android-version.md | 15 ++++++- .../Resolving-common-build-failures.md | 2 +- ...Changes-in-the-Devicelab-on-an-Emulator.md | 7 +++- .../Upgrading-Engine's-Android-API-version.md | 2 +- .../Upgrading-pre-1.12-Android-projects.md | 2 +- docs/platforms/android/Virtual-Display.md | 2 +- .../web/Debugging-issues-on-the-Web.md | 2 +- .../Postmortem-AndroidX-plugin-migration.md | 4 +- ...em-Platform-View-android-14-regression.md} | 31 +++++++++----- ...e-failures-on-Flutter-v1.12.13-hotfix.5.md | 20 +++++---- ...etrospective-Flutter-2.8-Stable-Release.md | 17 +++++++- docs/releases/Bad-Builds.md | 10 ++--- docs/releases/Flutter-Cherrypick-Process.md | 3 ++ docs/releases/Where's-my-commit.md | 2 +- docs/tool/README.md | 2 +- ...g-custom-embedders-with-the-Flutter-CLI.md | 2 +- docs/triage/README.md | 2 +- .../Workarounds-for-common-issues.md | 2 +- packages/flutter_tools/README.md | 2 +- 49 files changed, 229 insertions(+), 109 deletions(-) rename docs/postmortems/{Postmortem-Platform-View-android-14-regression => Postmortem-Platform-View-android-14-regression.md} (95%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0817c363750cb..e0569564f647e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -91,7 +91,12 @@ for how to set up your development environment, or ask in #hackers-test on Disco Developing for Flutter ---------------------- -If you would prefer to write code, you may wish to start with our list of good first issues for [Flutter](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) or for [Flutter DevTools](https://github.com/flutter/devtools/labels/good%20first%20issue). See the respective sections below for further instructions. +If you prefer to write code, consider starting with the list of good +first issues for [Flutter][flutter-gfi] or for [Flutter DevTools][devtools-gfi]. +Reference the respective sections below for further instructions. + +[flutter-gfi]: https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22 +[devtools-gfi]: https://github.com/flutter/devtools/labels/good%20first%20issue ### Framework and Engine @@ -162,7 +167,7 @@ API documentation ----------------- Another great area to contribute in is sample code and API documentation. If this is an area that interests you, join our -[Discord](./docs/contributing/Chat.md) server and introduce yourself on the #hackers-deverl, #hackers-framework, +[Discord](./docs/contributing/Chat.md) server and introduce yourself on the #hackers-devrel, #hackers-framework, or #hackers-engine channels, describing your area of interest. As our API docs are integrated into our source code, see the "developing for Flutter" section above for a guide on how to set up your developer environment. diff --git a/dev/conductor/README.md b/dev/conductor/README.md index f7fc1e9c4108a..a51d790ce8ff2 100644 --- a/dev/conductor/README.md +++ b/dev/conductor/README.md @@ -23,7 +23,7 @@ unlock your ssh key for the session; if you do not, each time the conductor attempts to interact with a remote, the user will be prompted to enter their ssh key password. -** Confirm that your personal github clone of flutter/flutter is named flutter and flutter/engine is named engine. If not you will need to use flags to override the defaults. +** Confirm that your personal GitHub clone of flutter/flutter is named flutter and flutter/engine is named engine. If not you will need to use flags to override the defaults. ## Usage diff --git a/dev/conductor/RELEASE_ONBOARDING.md b/dev/conductor/RELEASE_ONBOARDING.md index fdd41c429c880..9253bc33513cf 100644 --- a/dev/conductor/RELEASE_ONBOARDING.md +++ b/dev/conductor/RELEASE_ONBOARDING.md @@ -2,61 +2,70 @@ Googler facing documentation can be found at go/flutter-release-workflow. -### Responsiblity +### Responsibility Release engineer is responsible for: -* Branch alignment and/or Sheparding cherry picks +* Branch alignment and/or shepherding cherry picks * Decision making related to cherry pick risk * Verification that pre and post submits pass prior to publishing * Contributor facing communication -* Some public facing post release comunication +* Some public facing post release communication In the past (and possibly in the future) there was a distinction between a release engineer and release manager. -For now the responsiblitys are the same and we will refer to the person managing the release as a release engineer. +For now the responsibilities are the same and we will refer to the person managing the release as a release engineer. ## Onboarding -One time setup instructions for new or returning relase engineers. + +One time setup instructions for new or returning release engineers. ### Groups/Permissions -#### Join flutter-hackers on github +#### Join flutter-hackers on GitHub + https://github.com/orgs/flutter/teams/flutter-hackers/members #### [Googler only] Join mdb/flutter-infra + Possibly not required https://ganpati2.corp.google.com/propose_membership?parent=9147533327&child=$me.prod #### Join the flutter-announce google group + Ping any current release engineer to add you as an owner and give you publish access. https://groups.google.com/g/flutter-announce/members?q=role:owner&pli=1 TODO include screenshot #### [Googler only] Install tool-proxy-client -From a glinux machine run -`sudo apt install tool-proxy-client` + +From a glinux machine run `sudo apt install tool-proxy-client`. `tool-proxy-client` is the tool that enables/enforces 2 party authorization for controlled builds. #### [Googler only] Confirm access to release calendar + Public and Beta releases and timelines go/dash-team-releases #### [Googler only] Join release chatroom + Release hotline https://chat.google.com/room/AAAA6RKcK2k?cls=7 #### [Googler only] join mdb/flutter-release-team + Controls who can approve 2 party auth requests. https://ganpati2.corp.google.com/propose_membership?parent=100213927583&child=$me.prod #### Setup conductor + Conductor is a dart command line interface for common release tasks. Its instructions are in README.md. - #### [Googler only] Confirm access to Apple signing cert update doc + go/flutter-signing-apple-contracts Also confirm access to valentine entries listed in that doc. #### [Googler only] Access release engineer doc + Confirm access to go/release-eng-retros diff --git a/dev/devicelab/README.md b/dev/devicelab/README.md index 4e0fdde1675fe..92e01c3bd83dd 100644 --- a/dev/devicelab/README.md +++ b/dev/devicelab/README.md @@ -28,7 +28,7 @@ DeviceLab tests are run against physical devices in Flutter's lab (the Tasks specify the type of device they are to run on (`linux_android`, `mac_ios`, `mac_android`, `windows_android`, etc). When a device in the lab is free, it -will pickup tasks that need to be completed. +will pick up tasks that need to be completed. 1. If the task succeeds, the test runner reports the success and uploads its performance metrics to Flutter's infrastructure. Not all tasks record diff --git a/docs/Flutter-Self-Service-Index.md b/docs/Flutter-Self-Service-Index.md index d382ceaa6b460..2754985ded23d 100644 --- a/docs/Flutter-Self-Service-Index.md +++ b/docs/Flutter-Self-Service-Index.md @@ -126,7 +126,7 @@ Flutter provides multiple functionality through self-service services. Most of t [Link](./platforms/android/Testing-Android-Changes-in-the-Devicelab-on-an-Emulator.md) - Flutter Github Wiki page under the “Android Development” Section. + Flutter GitHub Wiki page under the “Android Development” Section. @@ -285,7 +285,7 @@ Flutter provides multiple functionality through self-service services. Most of t Link - Engine github security tab. + Engine GitHub security tab. diff --git a/docs/In-case-of-emergency.md b/docs/In-case-of-emergency.md index 74f92842b149c..e7f913b33efe1 100644 --- a/docs/In-case-of-emergency.md +++ b/docs/In-case-of-emergency.md @@ -1,6 +1,7 @@ ## If flutter.dev is down -If one of our web sites is down, please ping `@emergency` on our [Discord server](./contributing/Chat.md). +If one of our websites is down, +please ping `@emergency` on our [Discord server](./contributing/Chat.md). ## If you find a security vulnerability diff --git a/docs/README.md b/docs/README.md index 99f8d8210f0d6..26f7bc4f3d2ad 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ This wiki is primarily aimed at engineers building or making contributions to Flutter. -If you are new to Flutter, then you will find more general information on the Flutter project, including tutorials and samples, on our Web site at [flutter.dev](https://flutter.dev). For specific information about Flutter's APIs, consider our API reference which can be found at the [api.flutter.dev](https://api.flutter.dev/). +If you are new to Flutter, then you will find more general information on the Flutter project, including tutorials and samples, on our website at [flutter.dev](https://flutter.dev). For specific information about Flutter's APIs, consider our API reference which can be found at the [api.flutter.dev](https://api.flutter.dev/). If you want to know what we're likely to do in the future, our [roadmap](./roadmap/Roadmap.md) may be of interest. diff --git a/docs/about/Glossary.md b/docs/about/Glossary.md index 14656ffcb0152..eeb079a512838 100644 --- a/docs/about/Glossary.md +++ b/docs/about/Glossary.md @@ -8,9 +8,9 @@ Here are some terms that we use in the Flutter project and what they mean: - **Dynamic patching**. The ability to update the Dart code of an app in the field by downloading a patch (of sorts) and providing it to the Dart VM, probably requiring a restart of the application. -- **Embedder**. The core of the Flutter engine is platform agnostic. But platforms that run Flutter applications need platform specific logic to wire up rendering to the native window toolkit, handle input events, etc.. This platform specific logic is referred to as the Flutter embedder. Embedders interact with the engine using a [very low level C/C++ API](https://github.com/flutter/engine/blob/043d92c48abdebdad926569bc204a59c5cf20a11/shell/platform/embedder/embedder.h). While this API exposed by the engine to its embedders is platform agnostic, it is usually not suitable for developers used to the tools, frameworks and libraries on that specific platform (UIKit using Objective-C/Swift on iOS, or, Android APIs using Java on Android). To make interacting with the engine more ergonomic to developers on a specific platform, there are platform specific embedding APIs ([iOS](https://docs.flutter.io/objcdoc/) and [Android](https://docs.flutter.io/javadoc/)). These APIs provide higher level abstractions but are optional. +- **Embedder**. The core of the Flutter engine is platform agnostic. But platforms that run Flutter applications need platform specific logic to wire up rendering to the native window toolkit, handle input events, etc.. This platform specific logic is referred to as the Flutter embedder. Embedders interact with the engine using a [very low level C/C++ API](https://github.com/flutter/engine/blob/0a3423abd79c282c8a5e84a24e03733c98b31144/shell/platform/embedder/embedder.h). While this API exposed by the engine to its embedders is platform agnostic, it is usually not suitable for developers used to the tools, frameworks and libraries on that specific platform (UIKit using Objective-C/Swift on iOS, or, Android APIs using Java on Android). To make interacting with the engine more ergonomic to developers on a specific platform, there are platform specific embedding APIs ([iOS](https://api.flutter.dev/ios-embedder) and [Android](https://api.flutter.dev/javadoc/)). These APIs provide higher level abstractions but are optional. -- **Embedding**. Flutter provides "embedders" to port Flutter behavior to specific platforms, as defined elsewhere in this glossary. However, embedders use a [very low level C/C++ API](https://github.com/flutter/engine/blob/043d92c48abdebdad926569bc204a59c5cf20a11/shell/platform/embedder/embedder.h) which would feel unnatural to typical developers of a platform, e.g., Android or iOS. A Flutter "embedding" is a counterpart to an "embedder", which introduces common platform tools for interacting with Flutter. The Android embedding offers a `FlutterActivity`, `FlutterFragment`, `FlutterView`, etc: [Android embedding](https://docs.flutter.io/javadoc/). The iOS embedding offers a `FlutterViewController`, etc: [iOS embedding](https://docs.flutter.io/objcdoc/). An embedding + an embedder signifies the entire story of how Flutter ports to a specific platform. +- **Embedding**. Flutter provides "embedders" to port Flutter behavior to specific platforms, as defined elsewhere in this glossary. However, embedders use a [very low level C/C++ API](https://github.com/flutter/engine/blob/0a3423abd79c282c8a5e84a24e03733c98b31144/shell/platform/embedder/embedder.h) which would feel unnatural to typical developers of a platform, e.g., Android or iOS. A Flutter "embedding" is a counterpart to an "embedder", which introduces common platform tools for interacting with Flutter. The Android embedding offers a `FlutterActivity`, `FlutterFragment`, `FlutterView`, etc: [Android embedding](https://api.flutter.dev/javadoc/). The iOS embedding offers a `FlutterViewController`, etc: [iOS embedding](https://api.flutter.dev/ios-embedder). An embedding + an embedder signifies the entire story of how Flutter ports to a specific platform. - **Engine**. The C++ (and Java and ObjectiveC and...) side of Flutter. Defined in the `engine` repository. Includes Skia, Dart, and other low-level components. Exposed as `dart:ui` and other Dart libraries to author code. diff --git a/docs/about/The-Engine-architecture.md b/docs/about/The-Engine-architecture.md index 420e543b4ee29..147794823f95f 100644 --- a/docs/about/The-Engine-architecture.md +++ b/docs/about/The-Engine-architecture.md @@ -81,7 +81,7 @@ responsibility of the embedder to create and manage threads (and their message loops) for the Flutter engine. The embedder gives the Flutter engine task runners for the threads it manages. In addition to the threads managed by the embedder for the engine, the Dart VM also has its own thread pool. Neither the -Flutter engine or the embedder have any access to the threads in this pool. +Flutter engine nor the embedder have any access to the threads in this pool. ### Task Runner Configuration @@ -122,7 +122,7 @@ Interacting with the Flutter engine in any way must happen on the platform thread. Interacting with the engine on any other thread will trip assertions in unoptimized builds and is not thread safe in release builds. There are numerous components in the Flutter engine that are not thread safe. Once the Flutter -engine is setup and running, the embedder does not have to post tasks to any of +engine is set up and running, the embedder does not have to post tasks to any of the task runners used to configure the engine as long as all accesses to the embedder API are made on the platform thread. diff --git a/docs/contributing/Chat.md b/docs/contributing/Chat.md index 82790ce828ccb..36c2f2bc17b62 100644 --- a/docs/contributing/Chat.md +++ b/docs/contributing/Chat.md @@ -2,7 +2,7 @@ -The Flutter team uses a [Discord server](https://discord.com/channels/608014603317936148). [This is invite link for Flutter's Discord server](https://discord.gg/ht477J5PyH). Please do not share either link directly, instead share links to this page. +The Flutter team uses a [Discord server](https://discord.com/channels/608014603317936148). [This is the invite link for Flutter's Discord server](https://discord.gg/ht477J5PyH). Please do not share either link directly, instead share links to this page. The server is open to the public, though some channels are intended only for people who are actively contributing. **See the #welcome channel for instructions on posting to the server (you won't be able to see the channels until you acknowledge the rules there).** diff --git a/docs/contributing/Setting-up-the-Framework-development-environment.md b/docs/contributing/Setting-up-the-Framework-development-environment.md index bc36c36005d3a..4dfb8591a2ada 100644 --- a/docs/contributing/Setting-up-the-Framework-development-environment.md +++ b/docs/contributing/Setting-up-the-Framework-development-environment.md @@ -1,6 +1,6 @@ -## Preqrequisites +## Prerequisites - * Linux, Mac OS X, or Windows + * Linux, macOS, or Windows * `git` (used for source version control) diff --git a/docs/contributing/Style-guide-for-Flutter-repo.md b/docs/contributing/Style-guide-for-Flutter-repo.md index accb79cd19e30..f1c24c6e0c9bc 100644 --- a/docs/contributing/Style-guide-for-Flutter-repo.md +++ b/docs/contributing/Style-guide-for-Flutter-repo.md @@ -477,7 +477,7 @@ Unfortunately, the reality is that everyone starts knowing nothing, and we do no For this reason, avoid using terms without first defining them, unless you are linking to more fundamental documentation that defines that term without reference to the API you are documenting. -For example, a fancy widget in the Material library can refer to the `StatefulWidget` documentation and assume that the reader either knows about the `StatefulWidget` class, or can learn about it by following the link and then later returning to the documentation for the fancy widget. However, the documentation for the `StatefulWidget` class should avoid assuming that the reader knows what a `State` class is, and should avoid defering to it for its definition, because `State` could is likely to defer back to `StatefulWidget` and the reader would be stuck in a loop unable to grasp the basic principles. This is the documentation equivalent of a bootstrapping problem. +For example, a fancy widget in the Material library can refer to the `StatefulWidget` documentation and assume that the reader either knows about the `StatefulWidget` class, or can learn about it by following the link and then later returning to the documentation for the fancy widget. However, the documentation for the `StatefulWidget` class should avoid assuming that the reader knows what a `State` class is, and should avoid deferring to it for its definition, because `State` could is likely to defer back to `StatefulWidget` and the reader would be stuck in a loop unable to grasp the basic principles. This is the documentation equivalent of a bootstrapping problem. Another way to express this is that API documentation should follow a similar layering philosophy as code. The goal of documentation is not just to act as a refresher for experts, but to act as a tutorial for new developers. @@ -834,7 +834,7 @@ than "lasagna" code (where each section of the code is cleanly layered and separ ### Avoid using `extension`. Extension methods are confusing to document and discover. To an end developer, -they appear no different than the built in API of the class, and discovering +they appear no different than the built-in API of the class, and discovering the documentation and implementation of an extension is more challenging than for class members. @@ -1169,7 +1169,7 @@ documented top-level library intended to be imported by users. The definition of "New" changes as code grows and time passes. If the code needed a replacement version the odds of needing another replacement in the -future is higher. Instead find a name that represents the idea being being used +future is higher. Instead find a name that represents the idea being used or replaced. @@ -1205,7 +1205,7 @@ Example: TODOs should include the string TODO in all caps, followed by the GitHub username of the person with the best _context_ about the problem referenced by the TODO in -parenthesis. A TODO is not a commitment that the person referenced will fix the +parentheses. A TODO is not a commitment that the person referenced will fix the problem, it is intended to be the person with enough context to explain the problem. Thus, when you create a TODO, it is almost always your username that is given. diff --git a/docs/contributing/issue_hygiene/Making-animated-GIFs-of-Flutter-apps.md b/docs/contributing/issue_hygiene/Making-animated-GIFs-of-Flutter-apps.md index 08e763332dd7f..b79f592dc45ab 100644 --- a/docs/contributing/issue_hygiene/Making-animated-GIFs-of-Flutter-apps.md +++ b/docs/contributing/issue_hygiene/Making-animated-GIFs-of-Flutter-apps.md @@ -1,4 +1,4 @@ -Animated GIFs are useful for documentating animations. Here’s how to make them: +Animated GIFs are useful for documenting animations. Here's how to make them: ## Capturing video of an Android device diff --git a/docs/contributing/issue_hygiene/Popular-issues.md b/docs/contributing/issue_hygiene/Popular-issues.md index 1a5ba491ca6f1..53d6aa69bec12 100644 --- a/docs/contributing/issue_hygiene/Popular-issues.md +++ b/docs/contributing/issue_hygiene/Popular-issues.md @@ -2,7 +2,7 @@ When deciding what to work on, we usually focus on issues that have a lot of thu Some popular issues are topics on which we cannot find a good way to make progress. Since those issues where we _do_ make progress get closed, the result is that [the list of most-popular issues](https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) is now full of issues where we have conspicuously not made progress! -In the interests of transparency, this wiki page discusses the status of the ten most popular issues. It is only updated occasionally and so may not be entirely up to date; for the most up to date information, please see the latest comments on the relevant issue. (Please avoid asking for an update on issues, otherwise they become full of people asking for updates and nobody can find the actual updates.) +In the interests of transparency, this wiki page discusses the status of the ten most popular issues. It is only updated occasionally and so may not be entirely up to date; for the most up-to-date information, please see the latest comments on the relevant issue. (Please avoid asking for an update on issues, otherwise they become full of people asking for updates and nobody can find the actual updates.) _See also: [the list of popular issues including closed issues](https://github.com/flutter/flutter/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc), which shows that popular issues do get closed. 😅_ diff --git a/docs/contributing/testing/Flutter-Test-Fonts.md b/docs/contributing/testing/Flutter-Test-Fonts.md index 5514dc7494900..96c58189d4a22 100644 --- a/docs/contributing/testing/Flutter-Test-Fonts.md +++ b/docs/contributing/testing/Flutter-Test-Fonts.md @@ -18,6 +18,7 @@ Thanks to that, the `FlutterTest` font generally provides more precise and font- **Example** You can expect this test to pass on all platforms (currently with the exception of the web HTML renderer): + ```dart final painter = TextPainter( text: const TextSpan( @@ -35,6 +36,7 @@ expect(lineMetrics.descent, 3.5); // 0.25em * 14.0pt // 'text' is 4 glyphs. Most glyphs are as wide as they are tall. expect(lineMetrics.width, 14.0 * 4); ``` + While with the `Ahem` font you would get [slightly different metrics on different platforms](https://github.com/flutter/flutter/issues/62819), since they use different font engines to scale the font. ### Glyphs diff --git a/docs/contributing/testing/Writing-a-golden-file-test-for-package-flutter.md b/docs/contributing/testing/Writing-a-golden-file-test-for-package-flutter.md index c63921c5ca323..532b1a463bc45 100644 --- a/docs/contributing/testing/Writing-a-golden-file-test-for-package-flutter.md +++ b/docs/contributing/testing/Writing-a-golden-file-test-for-package-flutter.md @@ -4,7 +4,7 @@ _(This page is referenced by comments in the Flutter codebase.)_ **If you want to learn how to write a golden test for your package, see [the `matchesGoldenFile` API docs](https://api.flutter.dev/flutter/flutter_test/matchesGoldenFile.html).** This wiki page describes the special process specifically for the Flutter team itself. -Golden file tests for `package:flutter` use [Flutter Gold](https://flutter-gold.skia.org/?query=source_type%3Dflutter) for baseline and version management of golden files. This allows for golden file testing on Linux, Windows, MacOS and Web, which accounts for the occasional subtle rendering differences between these platforms. +Golden file tests for `package:flutter` use [Flutter Gold](https://flutter-gold.skia.org/?query=source_type%3Dflutter) for baseline and version management of golden files. This allows for golden file testing on Linux, Windows, macOS and Web, which accounts for the occasional subtle rendering differences between these platforms. ## Index @@ -150,9 +150,9 @@ Add an expectation along the following lines: ); ``` -The argument to `matchesGoldenFile` is the filename for the screen shot. The part up to the first dot should exactly match the test filename (e.g. if your test is `widgets/foo_bar_test.dart`, use `foo_bar`). The `subtest` part should be unique to this `testWidgets` entry, and the part after that should be unique within the `testWidgets` entry. This allows each file to have multiple `testWidgets` tests each with their own namespace for the images, and then allows for disambiguation within each test in case there are multiple screen shots per test. +The argument to `matchesGoldenFile` is the filename for the screenshot. The part up to the first dot should exactly match the test filename (e.g. if your test is `widgets/foo_bar_test.dart`, use `foo_bar`). The `subtest` part should be unique to this `testWidgets` entry, and the part after that should be unique within the `testWidgets` entry. This allows each file to have multiple `testWidgets` tests each with their own namespace for the images, and then allows for disambiguation within each test in case there are multiple screenshots per test. -Golden tests may be executed locally on Linux, MacOS, and Windows platforms. All reference images can be found at [Flutter Gold baselines](https://flutter-gold.skia.org/list?fdiffmax=-1&fref=false&frgbamax=255&frgbamin=0&head=true&include=false&limit=50&master=false&match=name&metric=combined&neg=false&new_clstore=true&offset=0&pos=true&query=source_type%3Dflutter&sort=desc&unt=true). Some tests may have multiple golden masters for a given test, to account for rendering differences across platforms. The parameter set for each image is listed in each image digest to differentiate renderings. +Golden tests may be executed locally on Linux, macOS, and Windows platforms. All reference images can be found at [Flutter Gold baselines](https://flutter-gold.skia.org/list?fdiffmax=-1&fref=false&frgbamax=255&frgbamin=0&head=true&include=false&limit=50&master=false&match=name&metric=combined&neg=false&new_clstore=true&offset=0&pos=true&query=source_type%3Dflutter&sort=desc&unt=true). Some tests may have multiple golden masters for a given test, to account for rendering differences across platforms. The parameter set for each image is listed in each image digest to differentiate renderings. Once you have written your test, run `flutter test --update-goldens test/foo/bar_test.dart` in the `flutter` package directory (where the filename is the relative path to your new test). This will update the images in `bin/cache/pkg/skia_goldens/packages/flutter/test/`; the directories below that will match the hierarchy of the directories in the `test` directory of the `flutter` package. Verify that the images are what you expect; update your test and repeat this step until you are happy with the image. diff --git a/docs/ecosystem/Plugins-and-Packages-repository-structure.md b/docs/ecosystem/Plugins-and-Packages-repository-structure.md index e8aabaf1c93d8..40fadc9e29057 100644 --- a/docs/ecosystem/Plugins-and-Packages-repository-structure.md +++ b/docs/ecosystem/Plugins-and-Packages-repository-structure.md @@ -29,10 +29,11 @@ Using the specific google hosted cache is not intended for contributors outside Googlers can debug locally by setting `ARTIFACT_HUB_REPOSITORY` to the valid artifact hub value and authenticating with GCP. To authenticate run `gcloud auth application-default login`. To find artifact hub url use `` section of go/artifact-hub#maven or inspect the value on CI servers. CI uses a service account for billing. That is defined in go/artifact-hub-service-account (Googler access only). -## Useful links for debuging -https://github.com/GoogleCloudPlatform/artifact-registry-maven-tools/blob/master/README.md -https://docs.gradle.org/current/userguide/declaring_repositories.html -https://docs.gradle.org/current/userguide/viewing_debugging_dependencies.html +## Useful links for debugging + +- https://github.com/GoogleCloudPlatform/artifact-registry-maven-tools/blob/master/README.md +- https://docs.gradle.org/current/userguide/declaring_repositories.html +- https://docs.gradle.org/current/userguide/viewing_debugging_dependencies.html Command to force refresh of dependencies `./gradlew app:dependencies --configuration --refresh-dependencies` diff --git a/docs/ecosystem/contributing/README.md b/docs/ecosystem/contributing/README.md index 4a4627911426d..88ebdf9659272 100644 --- a/docs/ecosystem/contributing/README.md +++ b/docs/ecosystem/contributing/README.md @@ -137,7 +137,7 @@ The goal is to have any plugin feature work on every platform on which that feat Given that, we welcome PRs that only implement a feature for a subset of platforms, including just one. To set expectations for how such PRs will be handled: - They will not be fully reviewed until there's an understanding of what support would look like across other platforms, for several reasons: - - API for features that will be permanently platform-specific may structured in ways that make that limitation more clear, so knowing if other platforms can support it will affect the review process. + - API for features that will be permanently platform-specific might be structured in ways that make that limitation more clear, so knowing if other platforms can support it will affect the review process. - We want to avoid over-fitting the plugin APIs to a single platform's API. It is often the case that several platforms can implement a feature, but the behavior is different enough across platforms that we need to design the API in a way that covers those variations in a cohesive way. This means that knowing at a high level what the implementation on other platform also affects the review process. - Features that are missing implementations on some platforms need to be clearly documented as such in the API, and those comments should clearly express whether those platform are temporarily missing implementations, or are not expected to ever have implementations due to platform limitations. @@ -163,7 +163,7 @@ if (somePluginInstance.supportsDoingThing) { rather than hard-coding a platform check. (See [`image_picker`'s `supportsImageSource`](https://github.com/flutter/packages/blob/9323e33ed9d8345d87514711dcaeb4cf4159ad1c/packages/image_picker/image_picker/lib/image_picker.dart#L309-L315) for an example.) This is for several reasons: - It is federation-friendly: a new implementation of the plugin (including the addition of 1P support for a previously-unsupported platform) will automatically be covered. -- It allow seamless adoption of new functionality: if we add previously-missing support to an existing implementation, clients will automatically benefit without any code changes on their part. +- It allows seamless adoption of new functionality: if we add previously-missing support to an existing implementation, clients will automatically benefit without any code changes on their part. - It makes our own documentation more evergreen: we've frequently had app-facing APIs that had a comment saying that an API is only available on platform X, and then forgotten to update it when adding support for platform Y. These APIs can take a variety of forms, including specific methods to check individual methods or parameters, a single method with an enum of API options, etc. Discuss with your reviewer what pattern is best suited to the specific case, and aim for consistency within a plugin when possible. @@ -197,7 +197,7 @@ Most of the plugins in flutter/packages are [federated](https://flutter.dev/docs We are investigating ways to streamline this, but currently the process for a multi-package PR is: -1. Create a PR that has all the changes, and update the pubspec.yamls to have path-based dependency overrides. This can be done with the [plugin repo tool](https://github.com/flutter/packages/blob/main/script/tool/README.md)'s `make-deps-path-based` command, targeting any dependency packages changed in the PR. For instance, for an Android-specific change to `video_player` that required platform interface changes as well: +1. Create a PR that has all the changes, and update the pubspec.yaml files to have path-based dependency overrides. This can be done with the [plugin repo tool](https://github.com/flutter/packages/blob/main/script/tool/README.md)'s `make-deps-path-based` command, targeting any dependency packages changed in the PR. For instance, for an Android-specific change to `video_player` that required platform interface changes as well: ``` $ dart run script/tool/bin/flutter_plugin_tools.dart make-deps-path-based --target-dependencies=video_player_platform_interface,video_player_android ``` @@ -238,7 +238,7 @@ This makes it easy for someone looking back at the change to find the reason for ### Changing platform interface method parameters -Because platform implementations are subclasses of the platform interface and override its methods, almost *any* change to the parameters of a method is a breaking change. In particular, adding an optional parameter to a platform interface method *is* a breaking change even though it doesn't break callers of the the method. +Because platform implementations are subclasses of the platform interface and override its methods, almost *any* change to the parameters of a method is a breaking change. In particular, adding an optional parameter to a platform interface method *is* a breaking change even though it doesn't break callers of the method. The least disruptive way to make a parameter change is: diff --git a/docs/ecosystem/contributing/Setting-up-the-Packages-development-environment.md b/docs/ecosystem/contributing/Setting-up-the-Packages-development-environment.md index a223ecb235676..0313d28643627 100644 --- a/docs/ecosystem/contributing/Setting-up-the-Packages-development-environment.md +++ b/docs/ecosystem/contributing/Setting-up-the-Packages-development-environment.md @@ -11,7 +11,7 @@ you already have a fork, and are now installing a development environment on a new machine, make sure you've updated your fork so that you don't use stale configuration options from long ago. - * If you haven't configured your machine with an SSH key that's known to github, then + * If you haven't configured your machine with an SSH key that's known to GitHub, then follow [GitHub's directions](https://help.github.com/articles/generating-ssh-keys/) to generate an SSH key. * `git clone git@github.com:/packages.git` diff --git a/docs/ecosystem/release/README.md b/docs/ecosystem/release/README.md index cccb0a9a220f9..882c167841d85 100644 --- a/docs/ecosystem/release/README.md +++ b/docs/ecosystem/release/README.md @@ -5,7 +5,7 @@ _See also: [Package migration to 1.0.0](../Package-migration-to-1.0.0.md) ## Automatic release -The packages in flutter/packages are automatically released with a Github Action workflow named [“release”](https://github.com/flutter/packages/blob/main/.github/workflows/release.yml). If a commit on master branch contains version updates to one or more packages, the “release” CI will publish the new versions to pub.dev and push the release tag to GitHub. The “release” CI passes if +The packages in flutter/packages are automatically released with a GitHub Action workflow named [“release”](https://github.com/flutter/packages/blob/main/.github/workflows/release.yml). If a commit on master branch contains version updates to one or more packages, the “release” CI will publish the new versions to pub.dev and push the release tag to GitHub. The “release” CI passes if 1. the release process is successful, or 2. there are no version updates in the commit, or 3. the new versions have already been published. diff --git a/docs/infra/Autorollers.md b/docs/infra/Autorollers.md index 2746826c1132b..19741da33f38a 100644 --- a/docs/infra/Autorollers.md +++ b/docs/infra/Autorollers.md @@ -2,7 +2,7 @@ Several of our dependencies are automatically rolled (updated) by bots. ## Clang to Engine -We use an auto-roller for Clang on [Linux](https://autoroll.skia.org/r/clang-linux-flutter-engine) and [MacOS](https://autoroll.skia.org/r/clang-mac-flutter-engine) (Windows is pending availability of a Windows Clang package from the Fuchsia infra team). In case of build failures or other errors, ping the #hackers-engine channel on [Discord](../contributing/Chat.md). +We use an auto-roller for Clang on [Linux](https://autoroll.skia.org/r/clang-linux-flutter-engine) and [macOS](https://autoroll.skia.org/r/clang-mac-flutter-engine) (Windows is pending availability of a Windows Clang package from the Fuchsia infra team). In case of build failures or other errors, ping the #hackers-engine channel on [Discord](../contributing/Chat.md). These rollers may fail if Clang catches a new compilation warning or error that it previously did not, or if a test relies on undefined behavior that has now changed in the new revision of Clang. It is best to resolve such issues ASAP to let the rollers continue and avoid a pile up of issues to resolve. @@ -10,7 +10,7 @@ The rollers work by updating a [CIPD](https://chrome-infra-packages.appspot.com/ ## Fuchsia SDK to Engine -We use an auto-roller for the Fuchsia SDK on [Linux](https://autoroll.skia.org/r/fuchsia-linux-sdk-flutter-engine) and [MacOS](https://autoroll.skia.org/r/fuchsia-mac-sdk-flutter-engine) (Windows is pending availability of a Windows Fuchsia SDK package from the Fuchsia infra team). In case of build failures or other errors, ping the #hackers-engine channel on [Discord](../contributing/Chat.md). +We use an auto-roller for the Fuchsia SDK on [Linux](https://autoroll.skia.org/r/fuchsia-linux-sdk-flutter-engine) and [macOS](https://autoroll.skia.org/r/fuchsia-mac-sdk-flutter-engine) (Windows is pending availability of a Windows Fuchsia SDK package from the Fuchsia infra team). In case of build failures or other errors, ping the #hackers-engine channel on [Discord](../contributing/Chat.md). These rollers may fail if the Fuchsia SDK contains a breaking change. It is best to resolve such issues ASAP to let the rollers continue and avoid a pile up of issues to resolve. @@ -18,7 +18,7 @@ The rollers work by updating a [CIPD](https://chrome-infra-packages.appspot.com/ ## Skia to Engine -We use an auto-roller for Skia rolls. It's status can be viewed at . In case of build failures or other errors, ping the Flutter-Skia chat channel. In case you get no response, you can login with an @google.com account and pause the roller (or ask someone with an @google.com account to do so). Please specify a descriptive reason and file a bug to re-enable the rollers as soon as possible. +We use an auto-roller for Skia rolls. It's status can be viewed at . In case of build failures or other errors, ping the Flutter-Skia chat channel. In case you get no response, you can log in with an @google.com account and pause the roller (or ask someone with an @google.com account to do so). Please specify a descriptive reason and file a bug to re-enable the rollers as soon as possible. The bot updates the `skia_revision` line of . diff --git a/docs/infra/Autosubmit-bot.md b/docs/infra/Autosubmit-bot.md index d75b10a85df1a..df10eed4d2506 100644 --- a/docs/infra/Autosubmit-bot.md +++ b/docs/infra/Autosubmit-bot.md @@ -1,8 +1,11 @@ # What is the Autosubmit Bot + The Flutter autosubmit bot is a tool that helps developers submit changes to the Flutter codebase. It automates the process of validating pull requests, test validation, and merging changes. This frees up developers to focus on writing code, and makes it easier to contribute to the Flutter project. # The Autosubmit Workflow + ## Submitting a Pull Request + When a developer opens a pull request against any of the currently supported repositories, the cocoon backend will schedule tests and checks against that pull request. Rather than have the developer wait around to make sure all these tests and validations have completed, they can add a label and the Autosubmit bot will then queue that pull request for merge upon successfully passing all checks and validations. It will look something like this: 1. You have a change you would like to contribute to flutter so you open a pull request. @@ -11,24 +14,30 @@ When a developer opens a pull request against any of the currently supported rep 4. If all validations are successful the Autosubmit bot will merge the pull request. ## What Validations does the Autosubmit Bot Perform + ### Code Reviews + The following are the rules for code reviews: * If the author is a member of the GitHub `flutter-hackers` org then they will need **at least 1 other review** from a member of the `flutter-hackers` org, preferable a code owner from that repository. * If the author is not a member of the GitHub `flutter-hackers` org then they will need **at least 2 other reviews** from members of the `flutter-hackers` org. * If any reviewer requests changes then regardless of the number of approvals you have the pull request will not be merged by the Autosubmit bot and the `autosubmit` label will be removed until the reviewer who requested changes has approved the pull request. ### Check Runs and Statuses -When a pull request is opened the Cocoon backend service will create a number of test runs that will be used to validate the code change that was submitted. Once the `autosubmit` label is added, the Autosubmit bot will check the statuses of those tests and will not merge the pull request until all of them have succeeded. If the any of the tests have failed the `autosubmit` label will be removed and the bot will no longer process that pull request. However the developer can re-trigger the test and add the label again to retry. + +When a pull request is opened the Cocoon backend service will create a number of test runs that will be used to validate the code change that was submitted. Once the `autosubmit` label is added, the Autosubmit bot will check the statuses of those tests and will not merge the pull request until all of them have succeeded. If any of the tests have failed the `autosubmit` label will be removed and the bot will no longer process that pull request. However the developer can re-trigger the test and add the label again to retry. ### Other Checks + The Autosubmit bot will make several other checks to determine viability of the pull request up until the moment the pull request is queued for merge. They are: * merge-ability - this is a GitHub status that says the code can be merged into the mainline branch. * code conflicts - the bot will check for this and notify the author in the event conflicts happen before merging of the pull request. ## Submitting a Revert Request + Autosubmit can also undo a change automatically simply by adding a label and a comment to a pull request. By adding the label 'revert' to a closed pull request the autosubmit bot will know to create a new request to revert this change and provide the specified reason in the body of the resulting revert request. ## Conditions on creating a Revert Request + * The initiator of the revert request must be a member of the flutter-hackers team. * The pull request being targeted for revert must have been merged less than 24 hours ago. * The initiator of the revert must supply a reason for the revert. In order to do this they must add a comment that begins with 'Reason for revert:' and then supply a reason for the revert. @@ -36,19 +45,23 @@ Autosubmit can also undo a change automatically simply by adding a label and a c If an empty reason is supplied then the 'revert' label will be removed and a comment supplied that you must supply a reason. # How it Works + ## Basic Design + The Autosubmit bot is a service hosted within GCP that listens to GitHub's webhook events utilizing PubSub to store the messages it is interested in for further processing. A cron job calls the service every two minutes to look for new events from GitHub to see if any new pull requests need to be processed. If an event contains a new pull request we look at it for the 'autosubmit' label. If the pull request is valid, i.e. it came from GitHub then we send it in a message to our PubSub topic. -A cron job will then call the Autosubmit service which will pull messages from the topic for processing and validation. If the pull request has passed the validations outlined above then the it will be merged and the PubSub message acknowledged. Autosubmit will no longer process that pull request. +A cron job will then call the Autosubmit service which will pull messages from the topic for processing and validation. If the pull request has passed the validations outlined above then it will be merged and the PubSub message acknowledged. Autosubmit will no longer process that pull request. {TODO add a diagram of the components} ## Configuration + The Autosubmit bot gets its configuration from a configuration file in the Orgs `.github` repository, specifically at `.github/autosubmit/autosubmit.yml`. These configurations govern the validations that the Autosubmit will perform and can be updated on the fly. These configs can also be overridden in other repositories so that the configuration can be tuned according to the repositories code owners liking. ### Configuration Values + | Config Name | Optional | Type | Default Value | Explanation | | --- | --- | --- | --- | --- | | `default_branch` | Yes | String | 'main' | the default branch of the repository where pull requests are merged into. This can be provided in the configuration but if it is not, the bot will collect this from a call to the Github API. | @@ -61,8 +74,10 @@ The Autosubmit bot gets its configuration from a configuration file in the Orgs | `required_checkruns_on_revert` | Yes | Array of String | [ ] | a list of check runs that Auto-submit will require to complete before merging a revert pull request regardless of what `support_no_review_revert` is set to. | ### Configuration File Examples + Here is an example of a full Autosubmit bot configuration file: -``` + +```yaml default_branch: main allow_config_override: false auto_approval_accounts: @@ -80,11 +95,13 @@ required_checkruns_on_revert: ``` An example of the minimum configuration file -``` + +```yaml approval_group: flutter-hackers ``` ### Allowing Configuration Overrides + All repositories within an Org need not follow the same rules. Some may want more Approvals for a review, some may not want to allow Reverts without a review. Autosubmit allows this by allowing an override configuration file to be defined in the repositories .github directory. This is different than the Org .github repository. In order to override the configuration at the Org level, the `allow_config_override` flag must be set to `true`. This tells Autosubmit that it will need to look in the local repositories .github directory for an autosubmit.yml file. Specifically that file will need to be places here: `/.github/autosubmit/autosubmit.yml`. @@ -97,7 +114,8 @@ The following rules will apply to override values: An example of Config Override: The Org level config is defined as follows: -``` + +```yaml allow_config_override: true auto_approval_accounts: - skia-flutter-autoroll @@ -111,7 +129,8 @@ required_checkruns_on_revert: ``` At the repository level the team would like to add a few more accounts to the `auto_approval_accounts` for automation purposes and required 1 more review but also would like revert requests to require reviews. So the repository level config would define the new values as follows: -``` + +```yaml auto_approval_accounts: - dependabot[bot] - dependabot @@ -121,7 +140,8 @@ support_no_review_revert: false ``` The final merged configuration for the repository would then become: -``` + +```yaml auto_approval_accounts: - skia-flutter-autoroll - engine-flutter-autoroll @@ -137,17 +157,21 @@ required_checkruns_on_revert: ``` # Where it Lives + The code for the Autosubmit bot is part of the flutter infra tools and can be found here: https://github.com/flutter/cocoon # Onboarding with Autosubmit {WIP} + ### Installing the Autosubmit App -Currently the bot is not available from the Github marketplace so it is only available to support internal Google Repositories. + +Currently the bot is not available from the GitHub marketplace so it is only available to support internal Google Repositories. In order to install the App you will need to: 1. Open a request with the Flutter Infrastructure team and request 'Autosubmit Support for ORG/REPO' in the title. 2. A Flutter Infrastructure Admin will then install the App on that repository so you must look out for a request from Autosubmit for the installation. 3. Next the bot will need to be added as a Pusher to the repository it will be servicing. This is done in the Branch Protections section of the repository. ### Adding the Configuration + After the app is installed you will need to place a configuration file into your ORGs .github repository. If you do not have one then you will need to create onc in your ORG level .github repository. Once the repository is created then you will need to add the Autosubmit configuration file at .github/autosubmit/autosubmit.yml. This is the primary location that Autosubmit will check first for the configuration. Repositories in your ORG can override the ORG level configs by placing a configuration file at repo/.github/autosubmit/autosubmit.yml. See the section on [configuration](Autosubmit-bot.md#configuration) above on the fields you may want to include in your configuration. @@ -155,11 +179,13 @@ Once the repository is created then you will need to add the Autosubmit configur Make sure that the App has read write access to the ORG level .github repository. ### Configuring the Repository + In order for the Autosubmit bot to merge pull requests it will need write access on the repository and it will need to be added to the branch protection section on who can push to the repository. An 'autosubmit' label will also need to be created for the supported repository. You can visit this [page](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels#creating-a-label) to view instructions on creating the label. ### Usage + Once the Autosubmit app has been installed in the repository, the configuration has been added and the target repository has been configured for write access you are ready to utilize the Autosubmit bot. In order to use the Autosubmit on pull requests in the target repository, follow these steps: 1. Open a pull request for review. 2. Make sure the pull request has tests as the bot will warn about this. diff --git a/docs/infra/Flutter-Framework-Gardener-Rotation.md b/docs/infra/Flutter-Framework-Gardener-Rotation.md index e6bf0f9a25d42..ebe3f8d4a8f46 100644 --- a/docs/infra/Flutter-Framework-Gardener-Rotation.md +++ b/docs/infra/Flutter-Framework-Gardener-Rotation.md @@ -21,6 +21,7 @@ As such, the gardener should use their badge and hat to: * Proactively communicate issues/status to others upstream/downstream. ## Rotation + Rotations are managed in the [Rotations tool]. The [Framework Gardener calendar] can be added to your calendar. Both of these links are currently Google internal. Team members are not expected to participate in multiple Flutter rotations. For example, those on the engine rotation are exempt and vice versa. New team members should be added to a single rotation, depending on the team to which they belong. @@ -28,6 +29,7 @@ Team members are not expected to participate in multiple Flutter rotations. For Before heading out on holiday, or if you get to your shift and find you can't do it, check the upcoming rotations and find a volunteer to swap shifts with while you're out. During some holiday periods when many team members are out and activity is particularly low on the tree, it may not be essential to have a dedicated gardener. ## Periodic scan + Open the [Framework build dashboard]. 1. If the tree is closed, identify which test shards are failing. If there are yellow boxes with an exclamation point, that means that the failed tests are automatically re-running themselves. The tree is not fully closed until there are solid red boxes or red boxes with exclamation points. You can begin investigation as soon as you notice the tree going red, but it is suggested not to begin escalation until re-runs have completed. 1. Identify which test within the shard failed, and try to locate obvious errors or failures in the logs. This procedure will be different if the failure is in [devicelab](#handling-a-devicelab-failure) or [LUCI](#handling-a-luci-failure). @@ -44,6 +46,7 @@ Open the [Framework build dashboard]. Unmute the [tree-status channel] and [hackers-infra channel] on [Discord]. Contributors are encouraged to escalate tree closures to you. Respond there as quickly as possible. ### Escalation + Escalate to the [test owner][TESTOWNERS]. File GitHub issues if none are already open. 1. The title should include the name of the failing test. 1. Assign the issue to the test owner with a `P1` priority. @@ -53,12 +56,14 @@ Escalate to the [test owner][TESTOWNERS]. File GitHub issues if none are already 1. Investigation updates and questions should not be posted in the [tree-status channel]. This channel should remain free of noise to discourage notification muting. ### Handling a devicelab failure + See [Why Flutter Devicelab Tests Break]. 1. If devicelab square (Android, Apple, or Windows icon) is red or yellow, click the square and click the _Download All Logs_ button. Note these logs may include the output from several test runs, since they will automatically rerun on failure to detect flakes. 1. If many different tests are failing on the same agent, this may be an indication of infra failure. File an [infrastructure ticket] if needed. 1. Note that phones occasionally require manual reboot. If this occurs, escalate on the [hackers-infra channel] on [Discord] file an [infrastructure ticket]. ### Handling a Firebase Test Lab failure + The devices in the Firebase test lab are not managed by the Flutter infra team. 1. The LUCI logs will typically list the device that the test failed for. Check the logs for a Firebase link that will contain logs from the failing device. [Example log](https://logs.chromium.org/logs/flutter/buildbucket/cr-buildbucket/8772117221814493585/+/u/test_execution/gcloud_firebase__2_/stdout). @@ -66,10 +71,12 @@ The devices in the Firebase test lab are not managed by the Flutter infra team. 1. Alternatively, check the LUCI log for instructions on how to notify Firebase via Slack. ### Handling a LUCI failure + 1. If Chrome icon (LUCI) square is red, click the red square and _Open Log for Build #1234_ to see the failing test in LUCI. 1. File an [infrastructure ticket] if needed. ### Reverting commits + If the test failure is not a known flake or infrastructure issue, revert the commit immediately. If the commit landed within the last 24 hours: @@ -99,6 +106,7 @@ If the failure is happening on an engine roll, contact the [Engine Sheriff chat] Coordinate with the engine sheriff on pausing and unpausing the [Engine to Framework autoroller] during this process. ### Handling a benchmark regression + Check [framework benchmarks] for regressions. File issues and escalate. Review [engine benchmarks] for any regressions. Choose the _Triage_ item on the left, and walk through new issues. For each commit that caused a regression you'll see marks in columns corresponding to the regression --- those marks indicate whether the results at that commit are low or high. @@ -108,7 +116,7 @@ Click a mark, and you'll be taken to a popup with the plot of recent data around 1. Click the commit to get a sub-popup with a link that can take you to the commit in question. If there is a new regression not deemed to be noise in a benchmark: -1. [Add a new issue to Github][new issue] +1. [Add a new issue to GitHub][new issue] 1. Label the issue with `team: benchmark`, and `severe:regression` labels. Label it with the `severe:performance` label if the benchmark is a performance one. 1. Paste a link to the performance plot from skia-perf into the bug. This is a "permalink", and will help others see what you're seeing. 1. Determine the CL at which the regression started and label with which part of the codebase might be causing the problem and whoever submitted the CL if possible. @@ -122,9 +130,11 @@ If there is a new regression not deemed to be noise in a benchmark: If it's noise, accept the benchmark by clicking the checkbox in the triage details popup. ### Handling a Skia gold failure + See the [golden test build breakage] guide. ## Filing an infra ticket + 1. Open a [new infra issue]. 1. Add a descriptive title. A message like "Add a LUCI builder for linux web engine" or "Debug gallery startup" is much more helpful than "quick request" or "test doesn't work?". 1. Clearly describe the issue or request in the description field. For example, if a ticket is requesting running several commands on the bots, the ticket should explain why, what commands are needed, on which bots and how to verify the results. @@ -143,12 +153,14 @@ See the [golden test build breakage] guide. 1. Click the create button. No need to set an assignee; infra oncall will handle all new tickets. ## Communication channels (public) + The bulk of communication happens on [Discord]. * Tree closure escalation and announcements: [tree-status channel]. * Infra issues: [hackers-infra channel] * Infrastructure tickets: File an [infrastructure ticket]. ## Communication channels (Google-internal) + * Engine issues: [🐣 Flutter Engine Sheriff ($USERNAME) ⛑️][Engine Sheriff chat] * LUCI help chat: [LUCI Users][LUCI Users chat] diff --git a/docs/infra/How-to-add-a-new-integration-test-to-Framework-CI.md b/docs/infra/How-to-add-a-new-integration-test-to-Framework-CI.md index c6134b0f37994..cf435c8d8808c 100644 --- a/docs/infra/How-to-add-a-new-integration-test-to-Framework-CI.md +++ b/docs/infra/How-to-add-a-new-integration-test-to-Framework-CI.md @@ -1,4 +1,4 @@ -This wiki is for [Framework](https://github.com/flutter/flutter) CI, and is not applicable to other repositories like Engine, Packages. The integration test is referred to an end-to-end target/test presented in [Flutter build dashboard](https://flutter-dashboard.appspot.com/#/build), which is an one-on-one mapping to the entries listed in the [.ci.yaml](https://github.com/flutter/flutter/blob/main/.ci.yaml) file. +This wiki is for [Framework](https://github.com/flutter/flutter) CI, and is not applicable to other repositories like Engine, Packages. The integration test is referred to an end-to-end target/test presented in [Flutter build dashboard](https://flutter-dashboard.appspot.com/#/build), which is a one-on-one mapping to the entries listed in the [.ci.yaml](https://github.com/flutter/flutter/blob/main/.ci.yaml) file. ## Overview Types of integration tests (based on how they are being executed): @@ -32,7 +32,7 @@ There is an overlap happens between `DeviceLab` and `Shard`: a single shard test Most likely, we can fit a new integration test to existing types, like `DeviceLab`, `Shard` or other case-by-case tests that use their own **`recipes`** in addition to `DeviceLab` and `Shard`, e.g. firebaselab, packaging, docs, etc. If your new test doesn't fit in any of these (very rarely), it may need a new recipe. > [!NOTE] -> **`Recipes`** are just python scripts detailing steps to setup env. and execute corresponding test harness. Different recipes basically mean different test harness with different environment setup. +> **`Recipes`** are just python scripts detailing steps to set up env. and execute corresponding test harness. Different recipes basically mean different test harness with different environment setup. For the two main types (`DeviceLab`/`Shard`): * if a new integration test needs a physical device, it should be under `DeviceLab` diff --git a/docs/infra/Landing-Changes-With-Autosubmit.md b/docs/infra/Landing-Changes-With-Autosubmit.md index a64bc74460130..4417b317c38e5 100644 --- a/docs/infra/Landing-Changes-With-Autosubmit.md +++ b/docs/infra/Landing-Changes-With-Autosubmit.md @@ -22,6 +22,7 @@ and should be used in conjunction with the `autosubmit` label. ### Usage Examples #### Merging a change (tree is open) + This is the happy path. The tree is green and you just need to make sure validations pass and have the correct number of reviews. @@ -34,6 +35,7 @@ sure validations pass and have the correct number of reviews. * mergeability #### Merging a fix on red tree-status (tree is closed) + This path should only be done in the event you have a change that will contribute a fix to the status of the tree. @@ -51,6 +53,7 @@ Warning: if you are not merging a fix for the tree you should not use the tree to open again. #### Reverting a change from the tree + This path is a way to revert a broken change from the tree that is within 24 hours old. @@ -69,16 +72,17 @@ assumed to be done out of urgency. * mergeability \* There are two types of required 'ci checks'. Ones that are controlled -by/through Github and those enforced through our auto-submit configuration +by/through GitHub and those enforced through our auto-submit configuration (TODO add link to the config). Currently there is only one required check in both cases but the later can be extended to support additional checks. #### Reverting older changes from the tree + This path describes what you should do in order to revert a change that is older than 24 hours. In this case you will need to open the revert request in the traditional way. -That is by navigating to your change in the Github UI and clicking the +That is by navigating to your change in the GitHub UI and clicking the 'Revert' button from the pull request page. The pull request will then need to be treated as a regular pull request where diff --git a/docs/infra/Reducing-Test-Flakiness.md b/docs/infra/Reducing-Test-Flakiness.md index ed491c8672122..f7b8fd52c4812 100644 --- a/docs/infra/Reducing-Test-Flakiness.md +++ b/docs/infra/Reducing-Test-Flakiness.md @@ -10,7 +10,9 @@ From [Flutter tree dashboard](https://flutter-dashboard.appspot.com/#/build), a ![Flake test runner](https://github.com/flutter/assets-for-api-docs/blob/main/assets/wiki/task_flake_test_runner.png) # Preventing flaky tests + ## [Adding a new DeviceLab test](https://github.com/flutter/flutter/tree/main/dev/devicelab#writing-tests) + DeviceLab tests are located under [`/dev/devicelab/bin/tasks`](https://github.com/flutter/flutter/tree/main/dev/devicelab/bin/tasks). If you plan to add a new DeviceLab test, please follow * Create a PR to add test files * Make sure an ownership entry is created for the test in [TESTOWNERS](https://github.com/flutter/flutter/blob/main/TESTOWNERS) file @@ -21,7 +23,9 @@ DeviceLab tests are located under [`/dev/devicelab/bin/tasks`](https://github.co * Switch `bringup` to `true`. # Detecting flaky tests -On a weekly basis, [an automation script](https://github.com/flutter/cocoon/blob/main/app_dart/lib/src/request_handlers/file_flaky_issue_and_pr.dart) will scan through test execution statistics over the past 15 days and identify top flaky ones + +On a weekly basis, [an automation script](https://github.com/flutter/cocoon/blob/main/app_dart/lib/src/request_handlers/file_flaky_issue_and_pr.dart) will scan through test execution statistics over the past 15 days and identify top flaky ones: + * If there are any test builders whose Flaky Ratio >= 2% * Create a tracking bug if not existing in the [bug pool](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+project%3Aflutter%2Fflutter%2F189+label%3A%22team%3A+flakes%22). * The sub-team TL will be assigned by default for further triage/re-assign. @@ -32,9 +36,11 @@ On a weekly basis, [an automation script](https://github.com/flutter/cocoon/blob If an issue is closed, there will be a grace period of 15 days before the automation script refile the issue if the same flakiness persists. # Triaging flaky tests + Figuring out how and why a set of tests is failing can be tricky. Here are a few tips to help kickstart the process. ## Use the generated ticket + The [auto-generated ticket](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+author%3Afluttergithubbot+label%3A%22severe%3A+flake%22) will provide links to: * An example of recent flakes on the same commit with a link to its Luci build page if available @@ -44,6 +50,7 @@ The [auto-generated ticket](https://github.com/flutter/flutter/issues?q=is%3Aope All of these pieces of information are helpful for further narrowing down the issue. ## Identify infrastructure issues + Things not directly related to the tests being run can be difficult to determine from the stdout logs. Things like timeouts are easier to determine using the `execution details` rather than `test_stdout`. From the Luci build page: * The failing step should have a red icon with an exclamation point and be expanded @@ -59,6 +66,7 @@ Some other common infra issues: * [Transient network issue](https://github.com/flutter/flutter/issues/99007) ## Identify failing tests + Sometimes, the reported error is not immediately obvious as to what test has failed. In these cases, digging into the `test_stdout` for clues can be helpful. From the Luci build page: * The failing step should have a red icon with an exclamation point and be expanded, e.g. step [`run flutter_view_ios__start_up`](https://ci.chromium.org/ui/p/flutter/builders/prod/Mac_ios%20flutter_view_ios__start_up/6939/overview). @@ -72,12 +80,15 @@ Sometimes, the reported error is not immediately obvious as to what test has fai * Search for "[E]" for shard tests flaking on a unit test ## Identifying a pattern + Flakes, by their nature, are inconsistent. Determining a pattern can be very helpful in figuring out what causes the issue, and may help in identifying a fix or workaround. The most useful tool for this is the flutter dashboard link provided by the ticket under "Recent test runs" which will filter to just the relevant flaky test set. E.g. [Linux_android flutter_gallery__transition_perf_with_semantics](https://flutter-dashboard.appspot.com/#/build?taskFilter=Linux_android+flutter_gallery__transition_perf_with_semantics) ### Verify repeating failures + Flakes are reported on the set of tests run, not specific test failures. This can mean that the issue raising us above our 2% threshold is actually more than one issue. This is pretty rare, but does happen on occasion. There's no need to waste a lot of time verifying that _every_ failure is the same, but taking some time to verify _some_ of the failures can save time in the long run. The list of "Flaky builds:" on the automated ticket is very useful for this, and you can often find additional flaky builds in the flutter dashboard. ### Find a first instance + Flakes can be under the 2% threshold for a long time and slowly build up from various small increases in flakiness. Other times they can have a specific cause that started in an obvious location. The latter are much easier to resolve, so it's a good idea to check for a root cause. In the Flutter dashboard: * Scroll down to load more builds @@ -90,6 +101,7 @@ Flakes can be under the 2% threshold for a long time and slowly build up from va * Compare the first instance of the flake with the previous successful run (see "Compare against successful runs" below for tips!) ### Compare against successful runs + Sometimes it can be easier to identify patterns of what's different between test runs than it is to identify a reason for the failure just from the failing runs. After you've identified what's failing, if you can't figure out what's causing the test to fail, keep an eye out for these common patterns: * Do the tests fail when they're run in a certain order? @@ -102,6 +114,7 @@ Sometimes it can be easier to identify patterns of what's different between test * If yes, it is most likely due to hardware issues, and can be routed to infra team for help. # Fixing flaky tests + The TL will help triage, reassign, and attempt to fix the flakiness. If the test was marked flaky in CI and then fixed, the test can be re-enabled after being validated for 50 consecutive runs without flakiness issues (task without exclamation point in flutter build dashboard and task not failed due to the same flaky failure). This can be done by updating the test entry in [.ci.yaml](https://github.com/flutter/flutter/blob/main/.ci.yaml) to remove the `bringup: true` entry for that target. diff --git a/docs/infra/Rolling-Dart.md b/docs/infra/Rolling-Dart.md index bd4a03955f734..e7090c3a0be65 100644 --- a/docs/infra/Rolling-Dart.md +++ b/docs/infra/Rolling-Dart.md @@ -54,9 +54,9 @@ If the script completes without errors, move on to step 10 in the next section t linked to from [our contributing guide](../../CONTRIBUTING.md). 2. Build the engine according to the instructions on the [Compiling the engine](../engine/contributing/Compiling-the-engine.md) page. 3. Select a target Dart revision, typically use the [latest revision](https://github.com/dart-lang/sdk/commits/main). Check that the tests for that revision have all passed (all green) on the [Dart buildbot](https://ci.chromium.org/p/flutter/g/engine/console) and the [Internal Dart Flutter buildbot](https://ci.chromium.org/p/dart/g/flutter/console). -4. Create a PR (see [Tree hygiene](../contributing/Tree-hygiene.md)) that updates `dart_revision` in [DEPS](https://github.com/flutter/engine/blob/main/DEPS) to your selected revision. Invoke `gclient sync` in the src directory to ensure versions corresponding to the DEPS file are synched up. +4. Create a PR (see [Tree hygiene](../contributing/Tree-hygiene.md)) that updates `dart_revision` in [DEPS](https://github.com/flutter/engine/blob/main/DEPS) to your selected revision. Invoke `gclient sync` in the src directory to ensure versions corresponding to the DEPS file are synced up. 5. Update all Dart-dependent DEPS entries using `engine/src/tools/dart/create_updated_flutter_deps.py` script. In case script complains that dart dependency was removed, remove entry from flutter DEPS file manually. If the list of library source files or patch files is modified, update the file [libraries.yaml](https://github.com/flutter/engine/blob/main/lib/snapshot/libraries.yaml) and regenerate the corresponding json file. -6. Invoke `gclient sync` in the src directory to ensure versions corresponding to the DEPS file are synched up +6. Invoke `gclient sync` in the src directory to ensure versions corresponding to the DEPS file are synced up. 7. Build the debug, profile, and release versions of the engine, following the normal [Compiling the engine](../engine/contributing/Compiling-the-engine.md) instructions. You will need to build the host versions of the engine too. Here is a script with the build commands: ```bash @@ -106,4 +106,4 @@ flutter test --local-engine=host_debug --local-engine-host=host_debug 13. Once the bot cycles green, the [Autorollers](../infra/Autorollers.md) will roll the engine into the flutter/flutter repo. When this happens, monitor the flutter [build bots](https://flutter-dashboard.appspot.com/build.html). If there is a failure, revert the Dart roll in flutter/engine, debug the problem and fix it or file a P0 issue against Dart. Please monitor the [flutter benchmarks dashboard](https://flutter-dashboard.appspot.com/benchmarks.html) and if any regressions are noticed please file P0 issues for all regressions **and revert the Dart roll**. The next roll is blocked until these issues/regressions are fixed. -14. When you are done please update the spread sheet at [http://go/dart-flutter-rolls](http://go/dart-flutter-rolls) with the git hash of the Dart revision that was rolled into the flutter engine. This hash will be used for rolling Dart into Google's internal code repository and would be picked as a potential candidate for a dev release. Also make sure you send an email to the next person on the list and make sure the person acknowledges picking up the roll baton. +14. When you are done please update the spreadsheet at [http://go/dart-flutter-rolls](http://go/dart-flutter-rolls) with the git hash of the Dart revision that was rolled into the flutter engine. This hash will be used for rolling Dart into Google's internal code repository and would be picked as a potential candidate for a dev release. Also make sure you send an email to the next person on the list and make sure the person acknowledges picking up the roll baton. diff --git a/docs/infra/Understanding-Google-Testing.md b/docs/infra/Understanding-Google-Testing.md index c24815184a9bd..a05662d40bc10 100644 --- a/docs/infra/Understanding-Google-Testing.md +++ b/docs/infra/Understanding-Google-Testing.md @@ -1,4 +1,4 @@ -"Google testing" is the test suite that Google runs to test a flutter pull request against their internal code base. This check shows up as one of the many check runs at the bottom of a open pull request. +"Google testing" is the test suite that Google runs to test a flutter pull request against their internal code base. This check shows up as one of the many check runs at the bottom of an open pull request. ![Screenshot 2023-02-24 at 3 45 33 PM](https://user-images.githubusercontent.com/38773539/221321907-edaca6c3-2165-4bfe-b436-00fcd64e820e.png) @@ -6,13 +6,13 @@ 1. Triggering google testing (<1 minute) - Google testing starts once an approval from a Flutter hacker is given. For Googlers, the check is run immediately. Google testing is triggered on GitHub webhooks, and uses a 30 minute cron job to backfill when webhooks are dropped. + Google testing starts once an approval from a Flutter hacker is given. For Googlers, the check is run immediately. Google testing is triggered on GitHub webhooks, and uses a 30-minute cron job to backfill when webhooks are dropped. 2. Running google testing (30 minutes) A subset of tests have been selected to run on presubmit as our smoke test suite. This gives quick, high coverage for PRs without running everything. -3. Propagating results back to Github (30 minutes) +3. Propagating results back to GitHub (30 minutes) Once Google Testing finishes, it takes up to 1 hour for the results to be propagated back to Github. Once the result is available on Github, it will show "Google Testing" as either "success" or "failure". diff --git a/docs/infra/Updating-dependencies-in-Flutter.md b/docs/infra/Updating-dependencies-in-Flutter.md index b097513061fa5..320583be4d338 100644 --- a/docs/infra/Updating-dependencies-in-Flutter.md +++ b/docs/infra/Updating-dependencies-in-Flutter.md @@ -8,7 +8,7 @@ Instead of manually updating dependencies in a `pubspec.yaml` file, use the [`up Sometimes you need to prevent a dependency from being updated when you run `flutter update-packages --force-upgrade`. -In that case, first pin the dependency in [`kManuallyPinnedDependencies`](https://github.com/flutter/flutter/blob/5bd34ef541575eddae6aaa82fc76a59ae7e464c3/packages/flutter_tools/lib/src/update_packages_pins.dart#L17) and a include a comment with a link to an issue to unpin the dependency. +In that case, first pin the dependency in [`kManuallyPinnedDependencies`](https://github.com/flutter/flutter/blob/5bd34ef541575eddae6aaa82fc76a59ae7e464c3/packages/flutter_tools/lib/src/update_packages_pins.dart#L17) and include a comment with a link to an issue to unpin the dependency. You can then re-run `flutter update-packages --force-upgrade`. diff --git a/docs/platforms/android/How-Flutter-apps-are-compiled-with-Gradle-for-Android.md b/docs/platforms/android/How-Flutter-apps-are-compiled-with-Gradle-for-Android.md index 88fca2736ac3c..4192fc144619f 100644 --- a/docs/platforms/android/How-Flutter-apps-are-compiled-with-Gradle-for-Android.md +++ b/docs/platforms/android/How-Flutter-apps-are-compiled-with-Gradle-for-Android.md @@ -90,7 +90,7 @@ For example: to compile with a stack trace that may or may not really point to the plugin's code on disk. - If the plugin's code conflicts with the app's Android source code (for - example, the plugin has a conflicting transitive dependancy), Gradle will + example, the plugin has a conflicting transitive dependency), Gradle will generally fail to compile with difficult to translate stack traces. - These subprojects are added in an `afterEvaluate` hook in `flutter.gradle`. Generally adding any logic in `afterEvaluate` blocks is discouraged because it diff --git a/docs/platforms/android/New-Android-version.md b/docs/platforms/android/New-Android-version.md index a0b3afd91cb6a..2c7219fba65b3 100644 --- a/docs/platforms/android/New-Android-version.md +++ b/docs/platforms/android/New-Android-version.md @@ -1,27 +1,34 @@ # Support a new Android API level Flutter (go/flutter-android-new-api-level) ## Objective + Provides a list of areas to consider and examples of former work for how to update Flutter to support a new version of the Android API. This happens every fall and Flutter developers expect to build against the latest versions quickly after they are available. ### Overview #### Bump compile and target SDK versions in samples + Samples, especially add to app samples, represent apps that mirror the first types of users we see adopt new Android APIs. Example PR: https://github.com/flutter/samples/pull/2368 #### New Android features + New Android features can require a broad spectrum of work. Some will require nothing from flutter. Some will require a lot of work, such as the support for “back preview”. The Android team generally needs to be aware and schedule work ahead of time. #### Update Gradle/AGP support -Sometimes newer versions of gradle are required to build without warning against a new version of Android API. The warning looks like + +Sometimes newer versions of gradle are required to build without warning against a new version of Android API. The warning looks like: + ``` WARNING:We recommend using a newer Android Gradle plugin to use compileSdkPreview = "somenamedversion" This Android Gradle plugin (X.X.X) was tested up to compileSdk = XX ``` + Bump the gradle version used in the engine. #### Update Robolectric + Robolectric is a dependency that allows us to write unit tests that run on a local development machine against the Android API surface without being on an Android device. Update what version of Robolectric we use in framework, engine and packages. @@ -64,10 +71,12 @@ Specifically the value for “--device” `./script/tool_runner.sh firebase-test Example PR: https://github.com/flutter/packages/pull/4430 #### Update documentation + Update documentation page to indicate the new API is tested https://docs.flutter.dev/reference/supported-platforms. #### Modify defaults + **In flutter/flutter:** Update default compile SDK version and target SDK version to the new API value. [Code here](../../../packages/flutter_tools/gradle/src/main/groovy/flutter.groovy). Follow comments in that file to update other locations that are assumed to be the same. @@ -90,11 +99,15 @@ https://github.com/flutter/engine/blob/9289cb6a36aa86990e3ffe0f20324dafa38e7c11/ **In flutter/packages:** Set examples to build with the new API. #### Test “Integration Test” package + Integration test is a package shipped in the Flutter tool for running integration tests on Flutter apps. Ensure that the integration test package has an example that targets the new API level on the most recent published stable version of the Flutter tool. #### Related documents + [Emulators for Flutter Android Testing (PUBLICLY SHARED)](https://docs.google.com/document/d/10wYUcLcSTF4Epg2EUGoBqOkkOe4zxKHvYKjXFZAOgGs/edit?resourcekey=0-pltjPvEtVezXDADMbUwFHQ) ### Additional notes + #### Upload new SDK version to CIPD and consume in buildroot + See [Upgrading Engine's Android API version](https://github.com/flutter/flutter/blob/main/docs/platforms/android/Upgrading-Engine's-Android-API-version.md) for instructions, as this work is also required to build the engine against the new Android version. diff --git a/docs/platforms/android/Resolving-common-build-failures.md b/docs/platforms/android/Resolving-common-build-failures.md index 6825f65e6b4f5..43c2dcdbcc80c 100644 --- a/docs/platforms/android/Resolving-common-build-failures.md +++ b/docs/platforms/android/Resolving-common-build-failures.md @@ -35,7 +35,7 @@ To resolve it: ### Gradle task assembleDebug failed with exit code 1 -If `assembleDebug` or `assembleRelease` failed but no error message can be seen, you are likely on a older Flutter version (`<= 1.9.1.hotfix4`) which may suppress the root cause of the error. +If `assembleDebug` or `assembleRelease` failed but no error message can be seen, you are likely on an older Flutter version (`<= 1.9.1.hotfix4`) which may suppress the root cause of the error. This problem can be solved in two ways: - Please try a more recent channel, like `beta` or `dev` and restart the compilation. It may still fail, but the error will now be printed diff --git a/docs/platforms/android/Testing-Android-Changes-in-the-Devicelab-on-an-Emulator.md b/docs/platforms/android/Testing-Android-Changes-in-the-Devicelab-on-an-Emulator.md index 9efb4e6c05738..7a9f19ec25362 100644 --- a/docs/platforms/android/Testing-Android-Changes-in-the-Devicelab-on-an-Emulator.md +++ b/docs/platforms/android/Testing-Android-Changes-in-the-Devicelab-on-an-Emulator.md @@ -1,14 +1,16 @@ ## Testing on Emulators in the Devicelab + While the Devicelab is typically for testing on Devices we have added support so that developers can now test Android changes via the LUCI recipes on an Android Emulator. -You can specify a new test via the .ci.yaml file in the repository. This allows the infra framework to run the test automatically with minimal work from the developer. +You can specify a new test via the `.ci.yaml` file in the repository. This allows the infra framework to run the test automatically with minimal work from the developer. ### Adding a Brand New Target + Adding a new Devicelab Android Emulator test for Android feature changes requires the following steps: Starting with the finished target yaml definition: -``` +```yaml - name: Linux_android android_defines_test recipe: devicelab/devicelab_drone presubmit: true @@ -51,6 +53,7 @@ Starting with the finished target yaml definition: f. `timeout` the timeout here is for the time to give the test to run before killing it. ### Updating an Existing Target + If you want to update an existing target you will only need to add the following changes: 1. add a `dimensions` field as described above. 2. Set the `device_type: "none"`. diff --git a/docs/platforms/android/Upgrading-Engine's-Android-API-version.md b/docs/platforms/android/Upgrading-Engine's-Android-API-version.md index 07232c9e068f0..f70c8399cbaef 100644 --- a/docs/platforms/android/Upgrading-Engine's-Android-API-version.md +++ b/docs/platforms/android/Upgrading-Engine's-Android-API-version.md @@ -47,7 +47,7 @@ This list may become outdated, so be sure to change any references to the old SD 1. Locate the desired Android Virtual Device (AVD) from https://chrome-infra-packages.appspot.com/p/chromium/tools/android/avd/linux-amd64/. You should look at the most recently updated AVD and verify that it has the desired `generic_android.textpb` for the API version that you are modifying the engine to support. Then, determine its build_id number by clicking on the AVD instance you would like to use and looking for the build_id tag. -2. In each of the engine builders (at the time of writing: `ci/builders/linux_android_emulator_skia.json` & `ci/builders/linux_android_emulator.json`), find the `android_virtual_device` and `avd_cipd_version` depedency entries and update them to the versions you desire, e.g. +2. In each of the engine builders (at the time of writing: `ci/builders/linux_android_emulator_skia.json` & `ci/builders/linux_android_emulator.json`), find the `android_virtual_device` and `avd_cipd_version` dependency entries and update them to the versions you desire, e.g. ```json { diff --git a/docs/platforms/android/Upgrading-pre-1.12-Android-projects.md b/docs/platforms/android/Upgrading-pre-1.12-Android-projects.md index 9c37e2fb32b5d..d076ec8f67e6c 100644 --- a/docs/platforms/android/Upgrading-pre-1.12-Android-projects.md +++ b/docs/platforms/android/Upgrading-pre-1.12-Android-projects.md @@ -20,7 +20,7 @@ _This guide assumes you haven't manually modified your Android host project for If you opt to migrate your standard `flutter create`d project, follow the following steps: -**1a.** If you don't have any of your own added code to `android/app/src/main/java/[your/package/name]/MainActivity.java` - remove the body of your `MainActivity.java` and change the `FlutterActivity` import. The new `FlutterActivity` no longer requires manually registering your plugins. It will now perform the registration automatically when the underlaying `FlutterEngine` is created. +**1a.** If you don't have any of your own added code to `android/app/src/main/java/[your/package/name]/MainActivity.java` - remove the body of your `MainActivity.java` and change the `FlutterActivity` import. The new `FlutterActivity` no longer requires manually registering your plugins. It will now perform the registration automatically when the underlying `FlutterEngine` is created. ```diff // MainActivity.java diff --git a/docs/platforms/android/Virtual-Display.md b/docs/platforms/android/Virtual-Display.md index 049cfc52d7155..c3af123894916 100644 --- a/docs/platforms/android/Virtual-Display.md +++ b/docs/platforms/android/Virtual-Display.md @@ -87,7 +87,7 @@ Flutter's View, not to the Android View they're actually trying to tap on. ### Background -Explaining our problems with accessbility (or "a11y") requires a brief detour +Explaining our problems with accessibility (or "a11y") requires a brief detour into explaining a11y itself on Android, and how a11y typically works on Flutter. Android itself builds up a tree of a11y nodes for each Android View rendered to diff --git a/docs/platforms/web/Debugging-issues-on-the-Web.md b/docs/platforms/web/Debugging-issues-on-the-Web.md index b4646ee00ac5a..2f5cb74926f86 100644 --- a/docs/platforms/web/Debugging-issues-on-the-Web.md +++ b/docs/platforms/web/Debugging-issues-on-the-Web.md @@ -1,6 +1,6 @@ # Debugging issues on the Web -The tips below can help you debug Web issues quicker and file more readable Github issues. +The tips below can help you debug Web issues quicker and file more readable GitHub issues. ## Chrome DevTools diff --git a/docs/postmortems/Postmortem-AndroidX-plugin-migration.md b/docs/postmortems/Postmortem-AndroidX-plugin-migration.md index 82e1c1ec551b4..19574a9d463ed 100644 --- a/docs/postmortems/Postmortem-AndroidX-plugin-migration.md +++ b/docs/postmortems/Postmortem-AndroidX-plugin-migration.md @@ -150,7 +150,7 @@ It looks like the only issue filed for this directly has been An explanation and migration path exists in the CHANGELOG.md of each plugin, but this information is hard to find and the actual Gradle error is not helpful. -Several bugs on Github have been filed from affected users. +Several bugs on GitHub have been filed from affected users. * [flutter/flutter#27106](https://github.com/flutter/flutter/issues/27106) * [flutter/flutter#27226](https://github.com/flutter/flutter/issues/27226) @@ -198,7 +198,7 @@ did not provide any obvious ways to debug the incompatibility. scale of the breakage. We didn't realize that it applied to all untouched `build.gradle` files produced by released versions of `flutter create`. Also failed to verify that the Gradle errors mentioned AndroidX or were otherwise - easily understable. + easily understandable. * The `flutter/plugins` CI failed to verify that the new plugins could be used with the template from `flutter create` on stable. * No manual sanity checks were recommended and insufficient ones were performed diff --git a/docs/postmortems/Postmortem-Platform-View-android-14-regression b/docs/postmortems/Postmortem-Platform-View-android-14-regression.md similarity index 95% rename from docs/postmortems/Postmortem-Platform-View-android-14-regression rename to docs/postmortems/Postmortem-Platform-View-android-14-regression.md index 3ba5338ba49fe..f3f6a344193ed 100644 --- a/docs/postmortems/Postmortem-Platform-View-android-14-regression +++ b/docs/postmortems/Postmortem-Platform-View-android-14-regression.md @@ -1,21 +1,26 @@ -Flutter postmortem: Platform-View-android-14-regression +# Flutter postmortem: Platform-View-android-14-regression + Status:Published Owners: johnmccutchen, reidbaker, jrect -##Summary +## Summary + Flutter “Platform Views” on Android 14 stopped displaying when apps were backgrounded and onMemoryTrim was called. Confounding investigation, the OEM had a different but related issue that impacted viewing Platform Views. Platform Views are particularly important because they are the mechanism used to display ads. Component: Android, Platform Views Date/time: 2024-05-28 Duration: 6 months -###Purpose of this doc +### Purpose of this doc + This is a postmortem for the regression in Flutter Platform Views on Android 14. The purpose is to understand what went wrong, why it took so long to diagnose and/or fix, and how to avoid such breakages and long resolution periods in the future. -###User Impact +### User Impact + All Flutter customers using Platform Views on Android 14, including apps that use ads for revenue. ### Root Cause(s) + An AOSP public Android API was subtly broken in the commit here. An OEM specific broken public API that was caused by similar roots but had different observable outcomes. Flutter integration tests did not catch this class of error. @@ -73,7 +78,7 @@ Timeline (all times in PST/PDT) 13:10 - Flutter team shares the model information so that we can get a build with the fix while awaiting an explanation of what is wrong. 2024-01-31 -00:00 - On an external bug with active comentary from multiple flutter contributors. Flutter still believes the issue to be the OEM only. https://github.com/pichillilorenzo/flutter_inappwebview/issues/1981#issuecomment-1919482839 +00:00 - On an external bug with active commentary from multiple flutter contributors. Flutter still believes the issue to be the OEM only. https://github.com/pichillilorenzo/flutter_inappwebview/issues/1981#issuecomment-1919482839 2024-02-16 @@ -181,20 +186,23 @@ medium (?) news: workaround isn't that bad at least, you'll need to switch to Ha 16:47 - Android rejected AOSP patch for partners. https://buganizer.corp.google.com/issues/339659092#comment12 2024-06-06 -Discussion among Flutter leads about whether the the OEM-specific workaround(s) that were CP’d into Flutter 3.22 should be reverted. The workarounds imply additional Flutter public APIs that are not believed to be sustainable. +Discussion among Flutter leads about whether the OEM-specific workaround(s) that were CP’d into Flutter 3.22 should be reverted. The workarounds imply additional Flutter public APIs that are not believed to be sustainable. https://github.com/flutter/flutter/issues/148417 3.22.2 released to the public with the second mitigation. Flutter apps need to recompile and republish. https://groups.google.com/g/flutter-announce/c/0PEE5AvDZqc End of outage. -###What went well: +### What went well + Once the Flutter team found the build range, the Android team fixed the problem for AOSP quickly. -###Where we got lucky: +### Where we got lucky + The issue did not affect all Platform Views on launch. Drawing on prior experience, the Flutter team was able to quickly bisect on Android builds. Presumably, most Android customers wouldn’t be able to do this. -###What could have gone better? +### What could have gone better? + The Flutter team struggled for several months to identify the difference between an Android issue from one manufacturer and an Android issue in AOSP. The root-causing effort could have been more collaborative. Platform Views are high risk and high value. @@ -210,11 +218,12 @@ Action items * P1 Screenshot Integration test for an arbitrary version of android that displays a platform view. * P2 Screenshot Integration test for an arbitrary version of android that displays a platform view after backgrounding the activity and triggering memory trim -###Process +### Process + go/critical-partner-patches this document describes the work to escalate android patches to other android manufacturers. go/pr-bug form required to get a patch shipped to pixel devices. -###Fixes +### Fixes https://googleplex-android-review.git.corp.google.com/c/platform/frameworks/base/+/27015418 https://github.com/flutter/engine/pull/52370 diff --git a/docs/postmortems/Postmortem-Widespread-Gradle-failures-on-Flutter-v1.12.13-hotfix.5.md b/docs/postmortems/Postmortem-Widespread-Gradle-failures-on-Flutter-v1.12.13-hotfix.5.md index 3ae4f5ef4af89..f72334cdfbc70 100644 --- a/docs/postmortems/Postmortem-Widespread-Gradle-failures-on-Flutter-v1.12.13-hotfix.5.md +++ b/docs/postmortems/Postmortem-Widespread-Gradle-failures-on-Flutter-v1.12.13-hotfix.5.md @@ -14,12 +14,15 @@ User impact: Users of the following plugins: url_launcher, google_sign_in, video ## Timeline (all times in PST/PDT) ### 2019-09-01 + stuartmorgan@ notices that Flutter applications that are using non-Android plugins are failing to build for Android (same for iOS) and files https://github.com/flutter/flutter/issues/39657. The root cause is that the Flutter gradle plugin assumes that all plugins include an Android implementation and tries to build it. ### 2019-09-16 + stuargmorgan@ prototypes [a fix](https://github.com/flutter/flutter/compare/main...stuartmorgan:wip-platform-plugin-files?expand=1). That fix requires migration of existing plugins. ### 2019-09-18 + As a temporary workaround for the issue above (Android only), amirh@ lands https://github.com/flutter/flutter/pull/40640 which makes `flutter.gradle` skip packages that do not have an `android/build.gradle` file, this workaround lives in the Flutter SDK and does not require plugin migration. The change lands with a test that: @@ -31,37 +34,42 @@ The change lands with a test that: In the following months work starts on federated web and mac implementations of `flutter/plugins` and `FirebaseExtended/flutterfire` plugins. With #40640 landed, these implementations all land without an `android/` folder. ### 2019-11-25 + blasten@ lands https://github.com/flutter/flutter/pull/45379 which reworks the Gradle workflow. This patch introduces a different code path for building transitive dependencies, the new code path again assumes that all plugins support `android/`. Though no one notices, and no tests fail (the test introduced in #40640 passes as flutter_plugin_test isn’t included as a transitive dependency). - ### 2019-12-06 + In preparation for the new pub.dev version that supports multi platform federated plugins and for the coming stable Flutter release the team decides to start endorsing web plugins (by adding them as a dependency of the app-facing plugins, so e.g url_launcher_web becomes a dependency of url_launcher). When staging the first PR for url_launcher, CI alerts us that the example application fails building for Android. After some investigation amirh@ and blasten@ figure out that https://github.com/flutter/flutter/pull/45379 introduced the regression. amirh@ starts adding a no-op `android/` implementations to the offending plugins, at the same time blasten@ sends https://github.com/flutter/flutter/pull/46282 which allows gradle to build apps with non Android plugins as transitive dependencies. At this point the release candidate for the next stable (1.12.13) was already cut without #46282. The logic in #46282 is somewhat similar to #40640 and skips packages that do not have an `android/` folder, amirh@ asks blasten@ whether we should be consistent with #46282 and check for `android/build.gradle` but both figure it shouldn’t matter and the PR lands as-is. - ### 2019-12-09 + The web team makes the case that #46282 should be cherry picked into 1.12.13 to avoid adding no-op `android/` folders to all web implementations. It’s cherry picked into v.12.13+hotfix.4 and the team decides to not add any more no-op `android/` implementations and endorse the existing with a minimal Flutter SDK constraint of `>=1.12.13+hotfix.4`. The team moves forward to publish the endorsements for: url_launcher, google_sign_in, video_player, firebase_auth, firebase_core, shared_preferences. At this point users of stable Flutter aren’t impacted as there is not yet a stable Flutter release which satisfies the version constraint, so pub won’t fetch the new plugin versions which include the endorsements. ### 2019-12-11 + 06:15pm - V1.12.13+hotfix.6 is released to stable **<START OF OUTAGE>** At this point, users of any of {url_launcher, google_sign_in, video_player, firebase_auth, firebase_core, shared_preferences} are affected by 2 issues: + #### 1. Android Studio users can’t build their apps + Android studio automatically creates an `android/` folder for all the Gradle subprojects during the “analyzing project phase”. This essentially disables the fix in #46282. (note that it does not create a build.gradle file.) This is not detected by CI as we’re not using Android Studio on CI. #### 2. Non fully AndroidX-compatible projects fail to build -The Flutter tool has a backup build strategy to deal with AndroidX failures - if the first build attempt fails due to an AndroidX issue, the Flutter tool tries a secondary build strategy which builds all plugins as AARs (this enables Jettifier). This AAR workflow was not updated to support non-Android plugins, which guarantees the build retry will fail if any of the affected plugins are included as dependencies. +The Flutter tool has a backup build strategy to deal with AndroidX failures - if the first build attempt fails due to an AndroidX issue, the Flutter tool tries a secondary build strategy which builds all plugins as AARs (this enables Jettifier). This AAR workflow was not updated to support non-Android plugins, which guarantees the build retry will fail if any of the affected plugins are included as dependencies. ### 2019-12-12 + 10:45am - amirh@ skims over new Flutter issues and notices multiple reports on Gradle errors due to plugins missing Android support and files https://github.com/flutter/flutter/issues/46898 to start tracking. While blasten@ is investigating the Gradle issue the team starts to mitigate by adding no-op `android/` implementations to the endorsed web plugins. @@ -69,6 +77,7 @@ While blasten@ is investigating the Gradle issue the team starts to mitigate by 01:34pm - All endorsed web plugins got a no-op `android/` folder **<END OF OUTAGE>** ### 2019-12-13 + blasten@ figures the underlying Gradle issue (https://github.com/flutter/flutter/issues/46898#issuecomment-565612416) and start working on a fix. @@ -109,21 +118,16 @@ Users of multiple popular Flutter plugins were not able to build their Android a ### Detection -{link to github issues for things that would have detected this failure before it became An Incident, such as better testing, monitoring, etc} - * All `dev/devicelab/bin/tasks/gradle_*` tests should run with the AAR workflow as well - https://github.com/flutter/flutter/issues/48089. * All `dev/devicelab/bin/tasks/gradle_*` tests should run with and without the projects being opened (and built?) by Android Studio - https://github.com/flutter/flutter/issues/48088. ### Process -{link to github issues for things that would have helped us resolve this failure faster, such as documented processes and protocols, etc} * A better process for flagging erupting fires quickly: * Alerts for issues that quickly gain thumb ups * Increased issue monitoring following a Flutter release ### Fixes -{link to github issues or PRs/commits for the actual fixes that were necessary to resolve this incident} - https://github.com/flutter/flutter/pull/47015 diff --git a/docs/postmortems/Retrospective-Flutter-2.8-Stable-Release.md b/docs/postmortems/Retrospective-Flutter-2.8-Stable-Release.md index a5002975f4396..b0758e878d7a9 100644 --- a/docs/postmortems/Retrospective-Flutter-2.8-Stable-Release.md +++ b/docs/postmortems/Retrospective-Flutter-2.8-Stable-Release.md @@ -1,8 +1,11 @@ # Flutter 2.8 Stable Retrospective + Date: 16 December 2021 Facilitator: Kevin Chisholm + ## Attendees + 1. Nuritzi Sanchez 1. Alexander Thomas 1. Godofredo Contreras @@ -17,23 +20,33 @@ Facilitator: Kevin Chisholm 1. Andrew Brogdon 1. Kevin Chisholm - ## Retrospective Guidelines + ### Blameless + Focus on the actions and behaviors, not the people. Our retrospectives should be a safe place to reflect on what we can do to improve as a team. + ### Inclusive + All input is valuable, we should never make someone feel as if their thoughts and contributions are not valued. + ### Actionable + Work toward defining the issues that can be actioned on to be more successful in the future. + ## Retrospective Items + ### What went well + * We released a quality SDK on the expected date. * No P0 issues to hotfix. * Our infrastructure and test owners responded rapidly to the chat allowing us to address issues. * The social team was proactive in keeping customers informed. * Were able to delay blog post and docs. * Got them out in time after the release was available. + ### Challenges + * We did not properly take into account how long the release would take. * We had no process to separate the build from the release. * Documentation is lacking / not prescriptive enough to accurately describe the entire process. @@ -55,6 +68,7 @@ Xcode/Mac/iOS were force updated in between the beta to stable time window * Branch configurations were updated after landing the PR causing multiple purples and several manual retries. ### How can we improve [30 Minutes] + * Build Flutter in advance. * Should have been done the day before and pushed the morning of. * Do most of the build and release process in advance; on the day-of, do the tagging / packaging work (<1 hr, and a predictable process). @@ -74,6 +88,7 @@ Xcode/Mac/iOS were force updated in between the beta to stable time window * Improve communication. * Cherry pick owners were not notified of the release times. * Were not able to resolve issues. + ### Action Items | Status | Action Item | Owner | diff --git a/docs/releases/Bad-Builds.md b/docs/releases/Bad-Builds.md index 94d33346e59e3..d67e6a7b2d0ec 100644 --- a/docs/releases/Bad-Builds.md +++ b/docs/releases/Bad-Builds.md @@ -1,6 +1,6 @@ ## Flutter Bad Builds Triage Guidelines (for Googlers) -1. If you encounter a serious P0 flutter production Google3 or a github issue, triage the issue and check if the issue is already part of Flutter's bad build [tracker](http://go/flutter-bad-builds). +1. If you encounter a serious P0 flutter production Google3 or a GitHub issue, triage the issue and check if the issue is already part of Flutter's bad build [tracker](http://go/flutter-bad-builds). If the issue is not listed in Flutter bad builds [tracker](http://go/flutter-bad-builds), check that it meets the below criteria to qualify for bad builds visibility - * A P0 bug * Can be in any component, Flutter’s component or Flutter user’s component @@ -8,10 +8,10 @@ If the issue is not listed in Flutter bad builds [tracker](http://go/flutter-bad * Must affect end-users, not a regression on tooling, debugging features, infra etc * Issue must be open -2. If there is a buganizer for this already and no github issue, create a github bug in the github repo. Label the github bug with label _a: production_ and _customer: google_. +2. If there is a buganizer for this already and no GitHub issue, create a GitHub bug in the GitHub repo. Label the GitHub bug with label _a: production_ and _customer: google_. 3. Add following information to Flutter bad builds visibility [tracker](http://go/flutter-bad-builds) - * Issue create date - this can be either buganizer or github issue create date + * Issue create date - this can be either buganizer or GitHub issue create date * Triaged by - your LDAP * Github issue id * Begin bad build commit hash URL (Commit hash URL can be from dart, engine, flutter and skia repos) @@ -19,8 +19,8 @@ If the issue is not listed in Flutter bad builds [tracker](http://go/flutter-bad 3. Automation will take care of finding the corresponding begin bad build commit CL based on the begin bad build commit URL you entered. Automation will run once every 12 hrs -4. Contact the [Flutter@Google team on-call ](https://rotations.corp.google.com/rotation/5644450090975232) for more visibility into the issue. This will also help identify duplicates across github & Google3. +4. Contact the [Flutter@Google team on-call ](https://rotations.corp.google.com/rotation/5644450090975232) for more visibility into the issue. This will also help identify duplicates across GitHub & Google3. 5. Once a fix has been merged, enter the “End bad build commit hash 1 URL”. -6. There are cases when a fix is merged as part of 2 different commits. In that case, you can use the “ End bad build commit hash 2 URL” column to populate the second commits hash information. Automation will take care of finding the corresponding End bad build commit CL based on the End bad build commit URL you entered. \ No newline at end of file +6. There are cases when a fix is merged as part of 2 different commits. In that case, you can use the "End bad build commit hash 2 URL" column to populate the second commits hash information. Automation will take care of finding the corresponding End bad build commit CL based on the End bad build commit URL you entered. \ No newline at end of file diff --git a/docs/releases/Flutter-Cherrypick-Process.md b/docs/releases/Flutter-Cherrypick-Process.md index 6e69c44ca830a..5ee331a1b24e5 100644 --- a/docs/releases/Flutter-Cherrypick-Process.md +++ b/docs/releases/Flutter-Cherrypick-Process.md @@ -1,11 +1,13 @@ # Flutter Cherry-pick Process ## Goal + With branching and branch testability being supported for Flutter & Dart releases, cherry-picking fixes is the preferred method to address issues for released software (beta and stable channels.) Stability of the release will be the overarching goal, so only highly impactful and critical cherrypicks will be allowed across Dart and Flutter. This document outlines the process for requesting and approval of cherrypicks. **Note: This process applies to regressions from the previous release or serious bugs otherwise introduced by the current release. Feature work is not considered for cherry-picking and will need to wait for the next release.** ## Automatically Creates a Cherry Pick Request + Eligibility: 1. If your cherry pick is expecting to have a merge conflict, please skip this section and follow instructions in the FAQ section below to manually open a cherry pick request instead. (e.g. PRs that contain changes to .ci.yaml files are very likely to hit a merge conflict) 2. The framework PR to be cherry picked needs to have a base commit later than [01/24/2024](https://www.google.com/url?q=https://github.com/flutter/flutter/pull/142058&sa=D&source=docs&ust=1706904517596608&usg=AOvVaw3cFfw8vyiBtY3EzM_N-PEi), and the engine PR to be cherry picked has a base commit later than [02/06/2024](https://github.com/flutter/engine/pull/50265) @@ -23,6 +25,7 @@ refer to the FAQ section below ## Frequently asked questions ### How do I request a cherry-pick? + To request a cherry-pick, utilize the [issue template](https://github.com/flutter/flutter/issues/new?template=7_cherry_pick.yml). ### Who can request a cherry-pick? diff --git a/docs/releases/Where's-my-commit.md b/docs/releases/Where's-my-commit.md index d22c546434eee..143616ff8a95c 100644 --- a/docs/releases/Where's-my-commit.md +++ b/docs/releases/Where's-my-commit.md @@ -104,7 +104,7 @@ To find out when a given Dart SDK change rolled into the engine: **Important**: be sure to adjust for timezones when comparing times between the Dart SDK commit and the time when the engine commits landed. -1. Once you've found a candidate commit, click on the hyperlink of the commit description to go to the commit details page. The full commit description will list what Dart SDK comitts were contained in the roll. For example: +1. Once you've found a candidate commit, click on the hyperlink of the commit description to go to the commit details page. The full commit description will list what Dart SDK commits were contained in the roll. For example: Commits contained in the Dart SDK roll diff --git a/docs/tool/README.md b/docs/tool/README.md index 3870cde18ea00..ed4a23fbd9808 100644 --- a/docs/tool/README.md +++ b/docs/tool/README.md @@ -72,7 +72,7 @@ or flutter test test_file_or_directory_path ``` -To run or debug the tests in IDE, make sure `FLUTTER_ROOT` directory is setup. +To run or debug the tests in IDE, make sure `FLUTTER_ROOT` directory is set up. For example, in Android Studio, select the configuration for the test, click "Edit Configurations...", under "Environment Variables" section, enter `FLUTTER_ROOT=directory_to_your_flutter_framework_repo`. diff --git a/docs/tool/Using-custom-embedders-with-the-Flutter-CLI.md b/docs/tool/Using-custom-embedders-with-the-Flutter-CLI.md index 23095e785df1c..cf15dac27bc67 100644 --- a/docs/tool/Using-custom-embedders-with-the-Flutter-CLI.md +++ b/docs/tool/Using-custom-embedders-with-the-Flutter-CLI.md @@ -59,7 +59,7 @@ Successfully added custom device to config file at "/home/hannes/.config/flutter/custom_devices.json". ``` -If your device is a little more complicated to setup, for example if your device is the one the flutter SDK is running on, you can configure it by editing the config file directly. (As mentioned above, I heavily recommend VS Code for that) +If your device is a little more complicated to set up, for example if your device is the one the flutter SDK is running on, you can configure it by editing the config file directly. (As mentioned above, I heavily recommend VS Code for that) ### That's it diff --git a/docs/triage/README.md b/docs/triage/README.md index 65a91b4d5eb42..3a22bfcef07f7 100644 --- a/docs/triage/README.md +++ b/docs/triage/README.md @@ -42,7 +42,7 @@ In the specific case of a bug with unclear steps to reproduce but very specific If you recognize that this bug is a duplicate of an existing bug, add a reference to that bug in a comment, then close the bug. Skip the remaining steps. As you triage more and more bugs you will become more and more familiar with the existing bugs and so you will get better and better at marking duplicates in this way. -When closing the duplicate bug, the github issue tracker does not copy the list of people being notified on the closed bug into the original bug. This can matter, especially when asking on the original bug for things like reproduction steps. Consider cc'ing the author of the duplicate issue into the original issue, especially if we're still trying to determine reproduction steps for the issue. +When closing the duplicate bug, the GitHub issue tracker does not copy the list of people being notified on the closed bug into the original bug. This can matter, especially when asking on the original bug for things like reproduction steps. Consider cc'ing the author of the duplicate issue into the original issue, especially if we're still trying to determine reproduction steps for the issue. ### Requests for help (documentation issues) diff --git a/docs/wiki_archive/Workarounds-for-common-issues.md b/docs/wiki_archive/Workarounds-for-common-issues.md index 8805ca5507890..0382040136cb9 100644 --- a/docs/wiki_archive/Workarounds-for-common-issues.md +++ b/docs/wiki_archive/Workarounds-for-common-issues.md @@ -103,7 +103,7 @@ To fix this package delete `///Users/someuser/.pub-cache/hosted/pub.dartlang.org In a network where the Internet can only be reached through a proxy and Flutter commands fail. -#### Symtoms +#### Symptoms // TODO diff --git a/packages/flutter_tools/README.md b/packages/flutter_tools/README.md index 19ce797a7c0f4..e527eb529b357 100644 --- a/packages/flutter_tools/README.md +++ b/packages/flutter_tools/README.md @@ -79,7 +79,7 @@ Please avoid setting any other timeouts. The integration tests can be configured to use a specific local engine variant by setting the `FLUTTER_LOCAL_ENGINE` and `FLUTTER_LOCAL_ENGINE_HOST` -environment svariable to the name of the local engines (e.g. `android_debug_unopt` +environment variables to the name of the local engines (e.g. `android_debug_unopt` and `host_debug_unopt`). If the local engine build requires a source path, this can be provided by setting the `FLUTTER_LOCAL_ENGINE_SRC_PATH` environment variable. This second variable is not necessary if the `flutter` and `engine`