firebase · Ehesp · Oct 1, 2020 · Jul 15, 2020 · Sep 15, 2020 · Sep 17, 2020
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,61 +1,118 @@
 # Contributing to FlutterFire
 
-[![Build Status](https://api.cirrus-ci.com/github/FirebaseExtended/flutterfire.svg)](https://cirrus-ci.com/github/FirebaseExtended/flutterfire/master)
+<a href="https://github.com/FirebaseExtended/flutterfire/actions?query=workflow%3Aall_plugins">
+  <img src="https://github.com/FirebaseExtended/flutterfire/workflows/all_plugins/badge.svg" alt="all_plugins GitHub Workflow Status"/>
+</a>
 
 _See also: [Flutter's code of conduct](https://flutter.io/design-principles/#code-of-conduct)_
 
-## Things you will need
+## 1. Things you will need
 
- * Linux, Mac OS X, or Windows.
- * git (used for source version control).
- * An ssh client (used to authenticate with GitHub).
+- Linux, Mac OS X, or Windows.
+- [git](https://git-scm.com) (used for source version control).
+- An ssh client (used to authenticate with GitHub).
+- An IDE such as [Android Studio](https://developer.android.com/studio) or [Visual Studio Code](https://code.visualstudio.com/).
+- [`flutter_plugin_tools`](https://pub.dartlang.org/packages/flutter_plugin_tools) locally activated.
+- [`tuneup`](https://pub.dev/packages/tuneup) locally activated.
 
-## Getting the code and configuring your environment
+## 2. Forking & cloning the repository
 
+- Ensure all the dependencies described in the previous section are installed.
+- Fork `https://github.com/FirebaseExtended/flutterfire` 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 [GitHub's directions](https://help.github.com/articles/generating-ssh-keys/)
+  to generate an SSH key.
+- `git clone [email protected]:<your_name_here>/flutterfire.git`
+- `git remote add upstream [email protected]:FirebaseExtended/flutterfire.git` (So that you
+  fetch from the master repository, not your clone, when running `git fetch`
+  et al.)
 
- * Ensure all the dependencies described in the previous section are installed.
- * Fork `https://github.com/FirebaseExtended/flutterfire` 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 [GitHub's directions](https://help.github.com/articles/generating-ssh-keys/)
-   to generate an SSH key.
- * `git clone [email protected]:<your_name_here>/flutterfire.git`
- * `cd plugins`
- * `git remote add upstream [email protected]:FirebaseExtended/flutterfire.git` (So that you
-   fetch from the master repository, not your clone, when running `git fetch`
-   et al.)
+## 3. Environment Setup
 
-## Running the examples
+FlutterFire uses [Melos](https://github.com/invertase/melos) to manage the project and dependencies.
 
+To install Melos, run the following command from your SSH client:
 
-To run an example with a prebuilt binary from the cloud, switch to that
-example's directory, run `pub get` to make sure its dependencies have been
-downloaded, and use `flutter run`. Make sure you have a device connected over
-USB and debugging enabled on that device.
+```bash
+pub global activate melos
+```
+
+Next, at the root of your locally cloned repository bootstrap the projects dependencies:
+
+```bash
+melos bootstrap
+```
+
+The bootstrap command locally links all dependencies within the project without having to
+provide manual [`dependency_overrides`](https://dart.dev/tools/pub/pubspec). This allows all
+plugins, examples and tests to build from the local clone project.
+
+## 4. Running an example
+
+Each plugin provides an example app which aims to showcase the main use-cases of each plugin.
 
- * `cd packages/cloud_firestore/cloud_firestore/example`
- * `flutter run`
+To run an example, run the `flutter run` command from the `example` directory of each plugins main
+directory. For example, for Cloud Firestore example:
 
-## Running the tests
+```bash
+cd packages/cloud_firestore/cloud_firestore/example
+flutter run
+```
+
+Using Melos (installed in step 3), any changes made to the plugins locally will also be reflected within all
+example applications code automatically.
+
+## 4. Running tests
+
+FlutterFire comprises of a number of tests for each plugin, either end-to-end (e2e) or unit tests.
 
-Flutter plugins have both unit tests of their Dart API and integration tests that run on a virtual or actual device.
+### Unit tests
 
-To run the unit tests:
+Unit tests are responsible for ensuring expected behaviour whilst developing the plugins Dart code. Unit tests do not
+interact with 3rd party Firebase services, and mock where possible. To run unit tests for a specific plugin, run the
+`flutter test` command from the plugins root directory. For example, Cloud Firestore platform interface tests can be run
+with the following commands:
 
+```bash
+cd packages/cloud_firestore/cloud_firestore_platform_interface
+flutter test
 ```
-flutter test test/<name_of_plugin>_test.dart
+
+### End-to-end (e2e) tests
+
+E2e tests are those which directly communicate with Firebase, whose results cannot be mocked. These tests run directly from
+an example application. To run e2e tests, run the `flutter drive` command from the plugins main `example` directory, targeting the
+entry e2e test file:
+
+```bash
+cd packages/cloud_firestore/cloud_firestore/example
+flutter drive --target=./test_driver/cloud_firestrore_e2e.dart
 ```
 
-To run the integration tests:
+To run tests against web environments, run the command as a release build:
 
+```bash
+cd packages/cloud_firestore/cloud_firestore/example
+flutter drive --target=./test_driver/cloud_firestrore_e2e.dart --release -d chrome
 ```
-cd example
-flutter drive test_driver/<name_of_plugin>.dart
+
+### Using Melos
+
+To help aid developer workflow, Melos provides a number of commands to quickly run
+tests against plugins. For example, to run all e2e tests across all plugins at once,
+run the following command from the root of your cloned repository:
+
+```bash
+melos run test:e2e
 ```
 
-## Contributing code
+A full list of all commands can be found within the [`melos.yaml`](https://github.com/FirebaseExtended/flutterfire/blob/master/melos.yaml)
+file.
+
+## 5. Contributing code
 
 We gladly accept contributions via GitHub pull requests.
 
@@ -67,37 +124,45 @@ keep the code consistent and avoid common pitfalls.
 
 To start working on a patch:
 
- * `git fetch upstream`
- * `git checkout upstream/master -b <name_of_your_branch>`
- * Hack away.
- * Verify changes with [flutter_plugin_tools](https://pub.dartlang.org/packages/flutter_plugin_tools)
-```
-pub global activate flutter_plugin_tools
-pub global run flutter_plugin_tools format --plugins plugin_name
-pub global run flutter_plugin_tools analyze --plugins plugin_name
-pub global run flutter_plugin_tools test --plugins plugin_name
+1. `git fetch upstream`
+2. `git checkout upstream/master -b <name_of_your_branch>`
+3. Hack away!
+
+Once you have made your changes, ensure that it passes the internal analyzer & formatting checks. The following
+commands can be run locally to highlight any issues before committing your code:
+
+```bash
+# Run the analyze check
+melos run analyze
+
+# Format code
+melos run format
 ```
- * `git commit -a -m "<your informative commit message>"`
- * `git push origin <name_of_your_branch>`
+
+Assuming all is successful, commit and push your code:
+
+1. `git commit -a -m "<your informative commit message>"`
+2. `git push origin <name_of_your_branch>`
 
 To send us a pull request:
 
-* `git pull-request` (if you are using [Hub](https://github.com/github/hub/)) or
+- `git pull-request` (if you are using [Hub](https://github.com/github/hub/)) or
   go to `https://github.com/FirebaseExtended/flutterfire` and click the
   "Compare & pull request" button
 
 Please make sure all your checkins have detailed commit messages explaining the patch.
 
-For pull requests that affect only one Flutterfire plugin, use a title that starts
-with the name of the plugin in brackets (e.g. [cloud_firestore]).
+When naming the title of your pull request, please follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4/)
+guide. For example, for a fix to the Cloud Firestore plugin:
+
+`fix(cloud_firestore): Fixed a bug!`
 
-Plugins tests are run automatically on contributions using Cirrus CI. However, due to
-cost constraints, pull requests from non-committers may not run all the tests
-automatically.
+Plugins tests are run automatically on contributions using GitHub Actions. Depending on 
+your code contributions, various tests will be run against your updated code automatically.
 
 Once you've gotten an LGTM from a project maintainer and once your PR has received
 the green light from all our automated testing, wait for one the package maintainers
-to merge the pull request and `pub submit` any affected packages.
+to merge the pull request.
 
 You must complete the
 [Contributor License Agreement](https://cla.developers.google.com/clas).
@@ -107,20 +172,17 @@ organization's) name and contact info to the [AUTHORS](AUTHORS) file.
 
 ### The review process
 
-* This is a new process we are currently experimenting with, feedback on the process is welcomed at the Gitter contributors channel. *
-
-Reviewing PRs often requires a non trivial amount of time. We prioritize issues, not PRs, so that we use our maintainers' time in the most impactful way. Issues pertaining to this repository are managed in the [flutter/flutter issue tracker and are labeled with "plugin"](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3Aplugin+sort%3Areactions-%2B1-desc). Non trivial PRs should have an associated issue that will be used for prioritization. See the [prioritization section](https://github.com/flutter/flutter/wiki/Issue-hygiene#prioritization) in the Flutter wiki to understand how issues are prioritized.
-
 Newly opened PRs first go through initial triage which results in one of:
-  * **Merging the PR** - if the PR can be quickly reviewed and looks good.
-  * **Closing the PR** - if the PR maintainer decides that the PR should not be merged.
-  * **Moving the PR to the backlog** - if the review requires non trivial effort and the issue isn't a priority; in this case the maintainer will:
-    * Make sure that the PR has an associated issue labeled with "plugin".
-    * Add the "backlog" label to the issue.
-    * Leave a comment on the PR explaining that the review is not trivial and that the issue will be looked at according to priority order.
-  * **Starting a non trivial review** - if the review requires non trivial effort and the issue is a priority; in this case the maintainer will:
-    * Add the "in review" label to the issue.
-    * Self assign the PR.
+
+- **Merging the PR** - if the PR can be quickly reviewed and looks good.
+- **Closing the PR** - if the PR maintainer decides that the PR should not be merged.
+- **Moving the PR to the backlog** - if the review requires non trivial effort and the issue isn't a priority; in this case the maintainer will:
+  - Make sure that the PR has an associated issue labeled with "plugin".
+  - Add the "backlog" label to the issue.
+  - Leave a comment on the PR explaining that the review is not trivial and that the issue will be looked at according to priority order.
+- **Starting a non trivial review** - if the review requires non trivial effort and the issue is a priority; in this case the maintainer will:
+  - Add the "in review" label to the issue.
+  - Self assign the PR.
 
 ### The release process
 
@@ -170,16 +232,15 @@ Install the tool by running:
 $ pub global activate flutter_plugin_tools
 ```
 
-Then, from the root of your local `flutter/plugins` repo, use the tool to
+Then, from the root of your locally cloned repository, use the tool to
 publish a release.
 
 ```terminal
 $ pub global run flutter_plugin_tools publish-plugin --package $package
 ```
 
 By default the tool tries to push tags to the `upstream` remote, but that and
-some additional settings can be configured. Run `pub global activate
-flutter_plugin_tools --help` for more usage information.
+some additional settings can be configured. Run `pub global activate flutter_plugin_tools --help` for more usage information.
 
 The tool wraps `pub publish` for pushing the package to pub, and then will
 automatically use git to try and create and push tags. It has some additional