Reorganize contributor documentation (#23963)
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..a253224
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,46 @@
+# Code of conduct
+
+We expect Flutter's contributors to act professionally and respectfully, and
+we expect our social spaces to be safe and dignified environments.
+
+Specifically:
+
+* Respect people, their identities, their culture, and their work.
+* Be kind. Be courteous. Be welcoming.
+* Listen. Consider and acknowledge people's points before responding.
+
+Should you experience anything that makes you feel unwelcome in Flutter's
+community, please contact someone on the team, for instance
+[Ian](mailto:ian@hixie.ch) or [Tim](mailto:timsneath@google.com). We will
+not tolerate harrasment from anyone in Flutter's community, even outside
+of Flutter's public communication channels.
+
+## Conflict resolution
+
+When multiple contributors disagree on the direction for a particular
+patch or the general direction of the project, the conflict should be
+resolved by communication. The people who disagree should get
+together, try to understand each other's points of view, and work to
+find a design that addresses everyone's concerns.
+
+This is usually sufficient to resolve issues. If you cannot come to an
+agreement, ask for the advice of a more senior member of the team.
+
+Be wary of agreement by attrition, where one person argues a point
+repeatedly until other participants give up in the interests of moving
+on. This is not conflict resolution, as it does not address everyone's
+concerns. Be wary of agreement by compromise, where two good competing
+solutions are merged into one mediocre solution. A conflict is
+addressed when the participants agree that the final solution is
+_better_ than all the conflicting proposals. Sometimes the solution is
+more work than either of the proposals. [Embrace the yak
+shave](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#lazy-programming).
+
+## Questions
+
+It's always ok to ask questions. Our systems are large, nobody will be
+an expert in all the systems. Once you find the answer, document it in
+the first place you looked. That way, the next person will be brought
+up to speed even quicker.
+
+[](https://xkcd.com/1053/https://xkcd.com/1053/)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dcde127..3f125ce 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,296 +3,73 @@
[](https://cirrus-ci.org/flutter/flutter)
-_See also: [Flutter's code of conduct](https://flutter.io/design-principles/#code-of-conduct)_
+_See also: [Flutter's code of conduct](CODE_OF_CONDUCT.md)_
Welcome
-------
-We gladly accept contributions via GitHub pull requests.
+We invite you to join our team! Everyone is welcome to contribute code
+via pull requests, to file issues on GitHub, to help people asking for
+help on our mailing lists or on Stack Overflow, to help triage,
+reproduce, or fix bugs that people have filed, to add to our
+documentation, or to help out in any other way.
-Please become familiar with our
-[style guide](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo) and
-[design philosophy](https://flutter.io/design-principles/). These guidelines are intended to
-keep the code consistent and avoid common pitfalls, and being familiar with them will
-make everything much easier for you. If you have questions about our processes or are looking
-for random tips and tricks, you may be interested in the [engine wiki](https://github.com/flutter/engine/wiki) and [framework wiki](https://github.com/flutter/flutter/wiki).
+We grant commit access (which includes full rights to the issue
+database, such as being able to edit labels) to people who have gained
+our trust and demonstrated a commitment to Flutter.
-This document will introduce you to the basic steps for developing for the Flutter framework (Dart).
-If you're interested in developing for the Flutter engine (C++, Java, Objective C), please
-switch to [the engine repo's `CONTRIBUTING.md` document](https://github.com/flutter/engine/blob/master/CONTRIBUTING.md).
+This document focuses on what is needed to contribute by writing code
+and submitting pull requests for the Flutter framework. For
+information on contributing in other ways, see [the community page
+on flutter.io](https://flutter.io/community).
-If you have an itch, work on that. If you are just looking for something good to start with, consider
-[the issues marked "easy fix"](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22easy+fix%22+sort%3Areactions-%2B1-desc) in our issues list.
+Developing for Flutter
+----------------------
-Things you will need
---------------------
+To develop for Flutter, you will eventually need to become familiar
+with our processes and conventions. This section lists the documents
+that describe these methodologies. The following list is ordered: you
+are strongly recommended to go through these documents in the order
+presented.
- * Linux, Mac OS X, or Windows
- * git (used for source version control).
- * An IDE. We recommend [Android Studio with the Flutter plugin](https://flutter.io/using-ide/).
- * An ssh client (used to authenticate with GitHub).
- * Python (used by some of our tools).
- * The Android platform tools (see [Issue #55](https://github.com/flutter/flutter/issues/55)
- about downloading the Android platform tools automatically).
- _If you're also working on the Flutter engine, you can use the
- copy of the Android platform tools in
- `.../engine/src/third_party/android_tools/sdk/platform-tools`._
- - Mac: `brew cask install android-platform-tools`
- - Linux: `sudo apt-get install android-tools-adb`
+1. [Our code of conduct](CODE_OF_CONDUCT.md), which stipulates explicitly
+ that everyone must be gracious, respectful, and professional. This
+ also documents our conflict resolution policy and encourages people
+ to ask questions.
-Getting the code and configuring your environment
--------------------------------------------------
+2. [Values](https://github.com/flutter/flutter/wiki/Values),
+ which talks about what we care most about.
- * Ensure all the dependencies described in the previous section, in particular
- git, ssh, and python are installed. Ensure that `adb`
- (from the Android platform tools) is in your path (e.g.,
- that `which adb` prints sensible output).
- * Fork `https://github.com/flutter/flutter` into your own GitHub account. If
- 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
- follow the directions here: https://help.github.com/articles/generating-ssh-keys/.
- * `git clone git@github.com:<your_name_here>/flutter.git`
- * `cd flutter`
- * `git remote add upstream git@github.com:flutter/flutter.git` (So that you
- fetch from the master repository, not your clone, when running `git fetch`
- et al.)
- * Add this repository's `bin` directory to your path. That will let you use the
- `flutter` command in this directory more easily.
- * Run `flutter update-packages` This will fetch all the Dart packages that
- Flutter depends on. You can replicate what this script does by running
- `pub get` in each directory that contains a `pubspec.yaml` file.
- * If you plan on using IntelliJ as your IDE, then also run
- `flutter ide-config --overwrite` to create all of the IntelliJ configuration
- files so you can open the main flutter directory as a project and run examples
- from within the IDE.
+3. [Setting up your engine development environment](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment),
+ which describes the steps you need to configure your computer to
+ work on Flutter's engine. If you only want to write code for the
+ Flutter framework, you can skip this step. Flutter's engine uses
+ mainly C++, Java, and ObjectiveC.
-Running the examples
---------------------
+4. [Setting up your framework development environment](https://github.com/flutter/flutter/wiki/Setting-up-the-Framework-development-environment),
+ which describes the steps you need to configure your computer to
+ work on Flutter's framework. Flutter's framework uses mainly Dart.
-To run an example, switch to that example's directory, and use `flutter run`.
-Make sure you have an emulator running, or a device connected over USB and
-debugging enabled on that device.
+4. [Tree hygiene](https://github.com/flutter/flutter/wiki/Tree-hygiene),
+ which covers how to land a PR, how to do code review, how to
+ handle breaking changes, how to handle regressions, and how to
+ handle post-commit test failures.
- * `cd examples/hello_world`
- * `flutter run`
+3. [Issue hygiene](https://github.com/flutter/flutter/wiki/Issue-hygiene),
+ which covers our processes around triaging bugs, escalating high
+ priority bugs, assigning bugs, and our GitHub labels and
+ milestones.
-You can also specify a particular Dart file to run if you want to run an example
-that doesn't have a `lib/main.dart` file using the `-t` command-line option. For
-example, to run the `widgets/spinning_square.dart` example in the [examples/layers](examples/layers)
-directory on a connected Android device, from that directory you would run:
-`flutter run -t widgets/spinning_square.dart`
+5. [Our style guide](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo),
+ which includes advice for designing APIs for Flutter, and how to
+ format code in the framework.
-When running code from the examples directory, any changes you make to the
-example code, as well as any changes to Dart code in the
-[packages/flutter](packages/flutter) directory and subdirectories, will
-automatically be picked when you relaunch the app. You can do the same for your
-own code by mimicking the `pubspec.yaml` files in the `examples` subdirectories.
-
-Running the analyzer
---------------------
-
-When editing Flutter code, it's important to check the code with the
-analyzer. There are two main ways to run it. In either case you will
-want to run `flutter update-packages` first, or you will get bogus
-error messages about core classes like Offset from `dart:ui`.
-
-For a one-off, use `flutter analyze --flutter-repo`. This uses the `analysis_options.yaml` file
-at the root of the repository for its configuration.
-
-For continuous analysis, use `flutter analyze --flutter-repo --watch`. This uses normal
-`analysis_options.yaml` files, and they can differ from package to package.
-
-If you want to see how many members are missing dartdocs, you should use the first option,
-providing the additional command `--dartdocs`.
-
-If you omit the `--flutter-repo` option you may end up in a confusing state because that will
-assume you want to check a single package and the flutter repository has several packages.
-
-
-Running the tests
------------------
-
-To automatically find all files named `_test.dart` inside a package's `test/` subdirectory, and
-run them inside the flutter shell as a test, use the `flutter test` command, e.g:
-
- * `cd examples/stocks`
- * `flutter test`
-
-Individual tests can also be run directly, e.g. `flutter test lib/my_app_test.dart`
-
-Flutter tests use [package:flutter_test](https://github.com/flutter/flutter/tree/master/packages/flutter_test)
-which provides flutter-specific extensions on top of [package:test](https://pub.dartlang.org/packages/test).
-
-`flutter test` runs tests inside the flutter shell. To debug tests in Observatory, use the `--start-paused`
-option to start the test in a paused state and wait for connection from a debugger. This option lets you
-set breakpoints before the test runs.
-
-To run analysis and all the tests for the entire Flutter repository, the same way that Cirrus runs them, run `dart dev/bots/test.dart` and `dart dev/bots/analyze.dart`.
-
-If you've built [your own flutter engine](#working-on-the-engine-and-the-framework-at-the-same-time), you
-can pass `--local-engine` to change what flutter shell `flutter test` uses. For example,
-if you built an engine in the `out/host_debug_unopt` directory, you can pass
-`--local-engine=host_debug_unopt` to run the tests in that engine.
-
-Flutter tests are headless, you won't see any UI. You can use
-`print` to generate console output or you can interact with the DartVM
-via observatory at [http://localhost:8181/](http://localhost:8181/).
-
-Adding a test
--------------
-
-To add a test to the Flutter package, create a file whose name
-ends with `_test.dart` in the `packages/flutter/test` directory. The
-test should have a `main` function and use the `flutter_test` package.
-
-Working with flutter tools
---------------------------
-
-The flutter tool itself is built when you run `flutter` for the first time and each time
-you run `flutter upgrade`. If you want to alter and re-test the tool's behavior itself,
-locally commit your tool changes in git and the tool will be rebuilt from Dart sources
-in `packages/flutter_tools` the next time you run `flutter`.
-
-Alternatively, delete the `bin/cache/flutter_tools.snapshot` file. Doing so will
-force a rebuild of the tool from your local sources the next time you run `flutter`.
-
-flutter_tools' tests run inside the Dart command line VM rather than in the
-flutter shell. To run the tests, ensure that no devices are connected,
-then navigate to `flutter_tools` and execute:
-
-```shell
-../../bin/cache/dart-sdk/bin/pub run test -j1
-```
-
-The pre-built flutter tool runs in release mode with the observatory off by default.
-To enable debugging mode and the observatory on the `flutter` tool, uncomment the
-`FLUTTER_TOOL_ARGS` line in the `bin/flutter` shell script.
-
-Using git
----------
-
-To start working on a patch:
-
- * `git fetch upstream`
- * `git checkout upstream/master -b name_of_your_branch`
- * Hack away.
- * `git commit -a -m "<your informative commit message>"`
- * `git push origin name_of_your_branch`
-
-To send us a pull request:
-
-* `git pull-request` (if you are using [Hub](http://github.com/github/hub/)) or
- go to `https://github.com/flutter/flutter` and click the
- "Compare & pull request" button
-
-Please make sure all your checkins have detailed commit messages explaining the patch.
-
-Once you've gotten an LGTM from a project maintainer and once your PR has received
-the green light from all our automated testing (running on Cirrus, etc), and once
-the tree is green (see the [design principles](https://flutter.io/design-principles/)
-document for more details), submit your changes to the `master` branch using one of
-the following methods:
-
-* Wait for one of the project maintainers to submit it for you.
-* Click the green "Merge pull request" button on the GitHub UI of your pull
- request (requires commit access)
-
-You must complete the
-[Contributor License Agreement](https://cla.developers.google.com/clas).
-You can do this online, and it only takes a minute.
-If you've never submitted code before, you must add your (or your
-organization's) name and contact info to the [AUTHORS](AUTHORS) file.
-
-We grant commit access to people who have gained our trust and demonstrated
-a commitment to Flutter.
-
-Tools for tracking and improving test coverage
-----------------------------------------------
-
-We strive for a high degree of test coverage for the Flutter framework. We use
-Coveralls to [track our test coverage](https://coveralls.io/github/flutter/flutter?branch=master).
-You can download our current coverage data from cloud storage and visualize it
-in Atom as follows:
-
- * Install [Atom](https://atom.io/).
- * Install the [lcov-info](https://atom.io/packages/lcov-info) package for Atom.
- * Open the `packages/flutter` folder in Atom.
- * Open a Dart file in the `lib` directory an type `Ctrl+Alt+C` to bring up the
- coverage data.
-
-If you don't see any coverage data, check that you have an `lcov.info` file in
-the `packages/flutter/coverage` directory. It should have been downloaded by the
-`flutter update-packages` command you ran previously.
-
-If you want to iterate quickly on improving test coverage, consider using this
-workflow:
-
- * Open a file and observe that some line is untested.
- * Write a test that exercises that line.
- * Run `flutter test --merge-coverage path/to/your/test_test.dart`.
- * After the test passes, observe that the line is now tested.
-
-This workflow merges the coverage data from this test run with the base coverage
-data downloaded by `flutter update-packages`.
-
-See [issue 4719](https://github.com/flutter/flutter/issues/4719) for ideas about
-how to improve this workflow.
-
-Communication
--------------
+In addition to the above, there are many pages on [our
+Wiki](https://github.com/flutter/flutter/wiki/) that may be of
+interest. For a curated list of pages see the sidebar on the wiki's
+home page. They are more or less listed in order of importance.
If you would like to chat to other people who work on Flutter, consider joining the
-https://gitter.im/flutter/contributors chat channel. (We also have a [general chat
+https://gitter.im/flutter/contributors chat channel. We also have a [general chat
channel](https://gitter.im/flutter/flutter) for people who aren't working on Flutter
-but who use Flutter.)
-
-Working on the engine and the framework at the same time
---------------------------------------------------------
-
-You can work both with this repository (flutter.git) and the Flutter
-[engine repository](https://github.com/flutter/engine) at the same time using
-the following steps.
-
-1. Follow the instructions above for creating a working copy of this repository.
-
-2. Follow the [contributing instructions](https://github.com/flutter/engine/blob/master/CONTRIBUTING.md)
- in the engine repository to create a working copy of the engine. The instructions
- also explain how to use a locally-built engine instead of the one bundled with
- your installation of the Flutter framework.
-
-Making a breaking change to the engine
---------------------------------------
-
-If you make a breaking change to the engine, you'll need to land your change in a
-few steps:
-
-1. Land your change in the engine repository.
-
-2. Publish a new version of the engine that contains your change. See the
- engine's [release process](https://github.com/flutter/engine/wiki/Release-process)
- for instructions about how to publish a new version of the engine. Publishing
- a new version is important in order to not break folks using prebuilt
- binaries in their workflow (e.g., our customers).
-
-API docs for master branch
---------------------------
-
-To view the API docs for the `master` branch,
-visit https://master-docs-flutter-io.firebaseapp.com/.
-
-Those docs should be updated after a successful CI build
-of Flutter's `master` branch.
-
-(Looking for the API docs for our releases?
-Please visit https://docs.flutter.io.)
-
-Build infrastructure
---------------------
-
-We build and test Flutter on:
-
-- [Cirrus](https://cirrus-ci.com/) ([details](.cirrus.yml))
-- Chromebots (a.k.a. "recipes", [details](dev/bots/README.md))
-- Devicelab (a.k.a. "cocoon", [details](dev/devicelab/README.md))
+but who use Flutter.
diff --git a/README.md b/README.md
index 592ccd1..ea9406f 100644
--- a/README.md
+++ b/README.md
@@ -12,8 +12,13 @@
**Main site: [flutter.io][]**
* [Install](https://flutter.io/get-started/install/)
* [Get started](https://flutter.io/get-started/)
+* [API documentation](https://docs.flutter.io/)
* [Changelog](https://github.com/flutter/flutter/wiki/Changelog)
-* [Contribute](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md#contributing-to-flutter)
+* [How to contribute](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md)
+
+For announcements about new releases and breaking changes, follow the
+[flutter-announce@googlegroups.com](https://groups.google.com/forum/#!forum/flutter-announce)
+mailing list.
## Fast development
@@ -128,52 +133,16 @@
you can use Flutter for your views and leverage much of your
existing Java/Kotlin/ObjC/Swift investment.
-### Build
-
-* **Beautiful app UIs**
- * Rich 2D GPU-accelerated APIs
- * Reactive framework
- * Animation/motion APIs
- * Material Design and iOS widgets
-* **Fluid coding experience**
- * Sub-second, stateful hot reload
- * IntelliJ: refactor, code completion, etc
- * Dart language and core libs
- * Package manager
-* **Full-featured apps**
- * Interop with mobile OS APIs & SDKs
- * Gradle/Java/Kotlin
- * Cocoapods/ObjC/Swift
-
-### Optimize
-
-* **Test**
- * Unit testing
- * Integration testing
- * On-device testing
-* **Debug**
- * IDE debugger
- * Web-based debugger
- * async/await aware
- * Expression evaluator
-* **Profile**
- * Timeline
- * CPU and memory
- * In-app perf charts
-
-### Deploy
-
-* **Compile**
- * Native ARM code
- * Dead code elimination
-* **Distribution**
- * App Store
- * Play Store
-
Learn more about what makes Flutter special in the
<a href="https://flutter.io/technical-overview/">technical overview</a>.
+# More resources
+
Join us in our [Gitter chat room](https://gitter.im/flutter/flutter) or join our public mailing list,
[flutter-dev@googlegroups.com](https://groups.google.com/forum/#!forum/flutter-dev).
+# How to contribute
+
+To join the team working on Flutter, see our [contributor guide](CONTRIBUTING.md).
+
[flutter.io]: https://flutter.io/
diff --git a/dev/bots/README.md b/dev/bots/README.md
index 77a4cf7..4644075 100644
--- a/dev/bots/README.md
+++ b/dev/bots/README.md
@@ -8,32 +8,41 @@
* https://build.chromium.org/p/client.flutter/console
- Additional testing and processing done after changes are submitted.
-The external master pages for the Chromium infra bots do not allow
-forcing new builds. Contact @eseidelGoogle or another member of
-Google's Flutter team if you need to do that.
+The Chromium infra bots do not allow forcing new builds from outside
+the Google network. Contact @eseidelGoogle or another Google member of
+the Flutter team if you need to do that.
-The [Cirrus](https://cirrus-ci.org)-based bots run the [`test.dart`](test.dart)
-script for each PR and submission. It does testing for the tools, for the
-framework, and (for submitted changes only) rebuilds and updates the master
-branch API docs staging site. For tagged dev and beta builds, it also builds and
-deploys the gallery app to the app stores.
+The [Cirrus](https://cirrus-ci.org)-based bots run the
+[`test.dart`](test.dart) script for each PR and submission. This does
+testing for the tools, for the framework, and (for submitted changes
+only) rebuilds and updates the master branch API docs staging site.
+For tagged dev and beta builds, it also builds and deploys the gallery
+app to the app stores. It is configured by the
+[.cirrus.yml](/.cirrus.yml).
-The rest of this document discusses only the Chromium infra bots.
+We also have post-commit testing with actual devices, in what we call
+our [devicelab](../dev/devicelab/README.md).
-This infrastructure is broken into two parts. A buildbot master specified by our
+## Chromium infra bots
+
+This part of our infrastructure is broken into two parts. A buildbot
+master specified by our
[builders.pyl](https://chromium.googlesource.com/chromium/tools/build.git/+/master/masters/master.client.flutter/builders.pyl)
file, and a [set of
recipes](https://chromium.googlesource.com/chromium/tools/build.git/+/master/scripts/slave/recipes/flutter)
-which we run on that master. Both of these technologies are highly specific to
-Google's Chromium project. We're just borrowing some of their infrastructure.
+which we run on that master. Both of these technologies are highly
+specific to Google's Chromium project. We're just borrowing some of
+their infrastructure.
-## Prerequisites
+### Prerequisites
+
+To work on this infrastructure you will need:
- [install depot_tools](http://www.chromium.org/developers/how-tos/install-depot-tools)
- Python package installer: `sudo apt-get install python-pip`
- Python coverage package (only needed for `training_simulation`): `sudo pip install coverage`
-## Getting the code
+### Getting the code
The following will get way more than just recipe code, but it _will_ get the recipe code:
@@ -49,7 +58,7 @@
unfortunately spread to many separate repositories. After checking out the code
search for files named `api.py` or `example.py` under `infra/build`.
-## Editing a recipe
+### Editing a recipe
Flutter has one recipe per repository. Currently
[flutter/flutter](https://chromium.googlesource.com/chromium/tools/build.git/+/master/scripts/slave/recipes/flutter/flutter.py)
@@ -79,7 +88,7 @@
4. Upload the patch (`git commit`, `git cl upload`) and send it to someone in
the `recipes/flutter/OWNERS` file for review.
-## Editing the client.flutter buildbot master
+### Editing the client.flutter buildbot master
Flutter uses Chromium's fancy
[builders.pyl](https://chromium.googlesource.com/infra/infra/+/master/doc/users/services/buildbot/builders.pyl.md)
@@ -94,7 +103,7 @@
docs](https://chromium.googlesource.com/infra/infra/+/master/doc/users/services/buildbot/builders.pyl.md)
to do so.
-## Future Directions
+### Future Directions
We would like to host our own recipes instead of storing them in
[build](https://chromium.googlesource.com/chromium/tools/build.git/+/master/scripts/slave/recipes/flutter).
@@ -103,7 +112,8 @@
in-progress. If you view the git log of this directory, you'll see we initially
tried, but it's not quite ready.
-# Android Tools
+
+### Android Tools
The Android SDK and NDK used by Flutter's Chrome infra bots are stored in Google Cloud. During the build a bot runs the
`download_android_tools.py` script that downloads the required version of the Android SDK into `dev/bots/android_tools`.
@@ -112,7 +122,7 @@
`download_android_tools.py` script, then `dev/bots/android_tools/sdk/tools/bin/sdkmanager --list`. If you find that some
components need to be updated or installed, follow the steps below:
-## How to update Android SDK on Google Cloud Storage
+#### How to update Android SDK on Google Cloud Storage
1. Run Android SDK Manager and update packages
`$ dev/bots/android_tools/sdk/tools/android update sdk`
@@ -132,7 +142,7 @@
5. Run upload_android_tools.py -t sdk
`$ dev/bots/upload_android_tools.py -t sdk`
-## How to update Android NDK on Google Cloud Storage
+#### How to update Android NDK on Google Cloud Storage
1. Download a new NDK binary (e.g. android-ndk-r10e-linux-x86_64.bin)
2. cd dev/bots/android_tools
@@ -151,6 +161,7 @@
`$ cd ../..`
`$ dev/bots/upload_android_tools.py -t ndk`
+
## Flutter codelabs build test
The Flutter codelabs exercise Material Components in the form of a
@@ -161,9 +172,9 @@
[Material Components for Flutter
Codelabs](https://github.com/material-components/material-components-flutter-codelabs)
can be built. This test serves as a smoke test for the Flutter
-framework and should not fail. Please address the issue from within
-your PR and rerun the test. If you feel that the test failing is not a
-direct result of changes made in your PR or that breaking this test is
-absolutely necessary, escalate this issue by [submitting an
+framework and should not fail. If it does, please address any issues
+in your PR and rerun the test. If you feel that the test failing is
+not a direct result of changes made in your PR or that breaking this
+test is absolutely necessary, escalate this issue by [submitting an
issue](https://github.com/material-components/material-components-flutter-codelabs/issues/new?title=%5BURGENT%5D%20Flutter%20Framework%20breaking%20PR)
to the MDC-Flutter Team.
