Issue #3411241: Expand ConverterCommand documentation to make it easier to run

scripts/src/ConverterCommand.php

@@ -19,10 +19,46 @@ use Symfony\Component\Filesystem\Filesystem;
  *
  * File usage:
  *
+ * This command can be used in 2 ways.
+ *
+ * ##### Local conversion when working on core merge requests. #####
+ *
+ * This requires a local core clone and a local contrib clone. The contrib clone
+ * should be on 3.0.x unless you are working on an issue that changes this file
+ * itself. The core clone should be on the core merge request branch. The
+ * contrib clone should NOT be inside the core clone. Both repositories should
+ * have a clean git status.
+ *
+ * If just testing the conversion or if you want to run code checks or phpunit
+ * tests locally on the core converted version you can just make a local branch
+ * in the core of 11.x or use 11.x directly if you are going to commit.
+ *
  * @code
- * composer core-covert /path/to/core merge-request-branch
+ * composer core-covert /path/to/core core-branch
  * @endcode
  *
+ * For example to update the Package Manager core merge requests.
+ *
+ * 1. Checkout 3.0.x on the core repo
+ * 2. Checkout the 3346707-package-manager branch from
+ *    https://drupal.org/9/3346707
+ * 3. Run:
+ *     `composer core-convert /path/to/core 3346707-package-manager --package_manager_only`
+ * 4. If the core checks pass the script will make a commit.
+ * 5. Sanity check files changes in the commit to ensure they are to
+ *    package manager only or related core composer files if needed.
+ * 6. To be extra careful you can run some or all phpunit tests locally on the
+ *    core converted version. Running the kernel tests or least the unit tests
+ *    might be a good idea.
+ * 7. Push the commit to the core merge request.
+ *
+ *
+ * ##### .gitlab-ci.yml usage #####
+ * Using the --gitlabci option tt is also used inside `.gitlab-ci.yml` to
+ * convert the contrib module to the core merge request version and run tests.
+ * This is to ensure, as much as possible, we can also convert to the core
+ * version and expect code quality checks and tests to pass.
+ *
  * The core clone should already have the core merge request locally.
  */
 class ConverterCommand extends Command {