Update tool README for packages use (#3882)
Updates to better reflect that this tooling is still used in flutter/packages, and how that differs from the flutter/plugins usage.
diff --git a/script/tool/README.md b/script/tool/README.md
index b759b9a..c142b66 100644
--- a/script/tool/README.md
+++ b/script/tool/README.md
@@ -5,46 +5,84 @@
for multi-package repositories, so your mileage may vary if using it in other
repositories.
-----
-
Note: The commands in tools are designed to run at the root of the repository or `<repository-root>/packages/`.
-To run the tool (in flutter/plugins):
+## Getting Started
+
+In flutter/plugins, the tool is run from source. In flutter/packages, the
+[published version](https://pub.dev/packages/flutter_plugin_tools) is used
+instead. (It is marked as Discontinued since it is no longer maintained as
+a general-purpose tool, but updates are still published for use in
+flutter/packages.)
+
+### From Source (flutter/plugins only)
+
+Set up:
```sh
-cd <path_to_plugins>/script/tool && dart pub get && cd ../../
+cd ./script/tool && dart pub get && cd ../../
+```
+
+Run:
+
+```sh
dart run ./script/tool/lib/src/main.dart <args>
```
-## Format Code
+### Published Version
+
+Set up:
```sh
-cd <path_to_plugins>
+dart pub global activate flutter_plugin_tools
+```
+
+Run:
+
+```sh
+dart pub global run flutter_plugin_tools <args>
+```
+
+## Commands
+
+Run with `--help` for a full list of commands and arguments, but the
+following shows a number of common commands.
+
+All examples assume running from source; see above for running the
+published version instead.
+
+Note that the `plugins` argument, despite the name, applies to any package.
+(It will likely be renamed `packages` in the future.)
+
+### Format Code
+
+```sh
+cd <repository root>
dart run /script/tool/lib/src/main.dart format --plugins plugin_name
```
-## Run static analyzer
+### Run the Dart Static Analyzer
```sh
-cd <path_to_plugins>
-pub run ./script/tool/lib/src/main.dart analyze --plugins plugin_name
+cd <repository root>
+dart run ./script/tool/lib/src/main.dart analyze --plugins plugin_name
```
-## Run Dart unit tests
+### Run Dart Unit Tests
```sh
-cd <path_to_plugins>
-pub run ./script/tool/lib/src/main.dart test --plugins plugin_name
+cd <repository root>
+dart run ./script/tool/lib/src/main.dart test --plugins plugin_name
```
-## Run XCTests
+### Run XCTests
```sh
-cd <path_to_plugins>
-dart run lib/src/main.dart xctest --target RunnerUITests --skip <plugins_to_skip>
+cd <repository root>
+dart run ./script/tool/lib/src/main.dart xctest --target RunnerUITests --skip <plugins_to_skip>
```
-## Publish and tag release
+### Publish a Release
``sh
cd <path_to_plugins>
@@ -63,6 +101,16 @@
directory and refuse to publish if there are any mismatched files with version
control present.
-There is a lot about this process that is still to be desired. Some top level
-items are being tracked in
-[flutter/flutter#27258](https://github.com/flutter/flutter/issues/27258).
+Automated publishing is under development. Follow
+[flutter/flutter#27258](https://github.com/flutter/flutter/issues/27258)
+for updates.
+
+## Updating the Tool
+
+For flutter/plugins, just changing the source here is all that's needed.
+
+For changes that are relevant to flutter/packages, you will also need to:
+- Update the tool's pubspec.yaml and CHANGELOG
+- Publish the tool
+- Update the pinned version in
+ [flutter/packages](https://github.com/flutter/packages/blob/master/.cirrus.yml)
