docs(upgrade): update readme, include new commands and migrations (#1…

…1695)

* docs(upgrade): update readme, include new commands and migrations

* chore(upgrade): format readme

packages/upgrade/README.md

@@ -25,27 +25,54 @@ You can install `@carbon/upgrade` in your project, or use a tool like
 by running the following command in your project:
 
 ```bash
-npx @carbon/upgrade -d
+npx @carbon/upgrade
 ```
 
 Below is a full output of the options and commands available:
 
 ```bash
 Usage: @carbon/upgrade [options]
 
+Commands:
+  @carbon/upgrade upgrade                   upgrade your project       [default]
+  @carbon/upgrade migrate <migration>       run a Carbon migration on your
+  [paths...]                                source files
+  @carbon/upgrade migrate list              list all available migrations
+
 Options:
       --help     Show help                                             [boolean]
       --version  Show version number                                   [boolean]
       --force    force execution if the cli encounters an error while doing
                  safety checks                        [boolean] [default: false]
   -w, --write    update the files with changes found by running the migration
-                                                                [default: false]
+                                                      [boolean] [default: false]
   -v, --verbose  optionally include additional logs, useful for debugging
                                                       [boolean] [default: false]
 ```
 
+### Migrations
+
+Included within the CLI are a number of migrations available to you to be ran on
+your project's source files.
+
+Migrations are automated scripts (codemods) ran using the
+[jscodeshift](https://github.com/facebook/jscodeshift) runner, that will apply
+intelligent transformations to your code.
+
+These migrations range from simple automations like a find and replace of import
+statements, to more sophisticated migrations that rewrite component prop usage,
+configuration, and set up. The source of these migrations can be viewed within
+the
+[transforms folder](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade/transforms).
+Each is tested against a series of test fixtures to ensure transforms are
+predictable and consistently provide the intended output.
+
 ## 🙌 Contributing
 
+If you have ideas on how we could make your migration experience easier, please
+reach out by
+[opening a new discussion](https://github.com/carbon-design-system/carbon/discussions/new).
+
 We're always looking for contributors to help us fix bugs, build new features,
 or help us improve the project documentation. If you're interested, definitely
 check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀