Reorganize contributor documentation (#23963)

CODE_OF_CONDUCT.md

+# 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.
+
+[!["I try not to make fun of people for admitting they don't know things, because for each thing 'everyone knows' by the time they're adults, every day there are, on average, 10,000 people in the US hearing about it for the first time. If I make fun of people, I train them not to tell me when they have those moments. And I miss out on the fun." "Diet coke and mentos thing? What's that?" "Oh man! We're going to the grocery store." "Why?" "You're one of today's lucky 10,000." (xkcd, May 2012)](https://imgs.xkcd.com/comics/ten_thousand.png)](https://xkcd.com/1053/https://xkcd.com/1053/)

README.md

@@ -12,8 +12,13 @@ Flutter is Google’s mobile app SDK for crafting high-quality native interfaces
 **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 @@ If you are an experienced iOS or Android developer,
 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/

dev/bots/README.md

@@ -8,32 +8,41 @@ The results of such builds are viewable at:
 * 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 @@ Most of the functionality for recipes comes from `recipe_modules`, which are
 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 @@ The typical cycle for editing a recipe is:
 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 @@ https://build.chromium.org/p/client.flutter.  Carefully follow the [builders.pyl
 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 @@ recipes](https://github.com/luci/recipes-py/blob/master/doc/cross_repo.md) is
 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 @@ To check which components are currently installed, download the current SDK stor
 `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 @@ components need to be updated or installed, follow the steps below:
 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 @@ components need to be updated or installed, follow the steps below:
    `$ 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 @@ The Flutter codelabs build test ensures that the final version of the
 [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.