From 183876fb47398ffeaf8e1b43056371ad4cf24509 Mon Sep 17 00:00:00 2001
From: Ted Bowman <41201-tedbow@users.noreply.drupalcode.org>
Date: Thu, 28 Dec 2023 17:28:16 +0000
Subject: [PATCH] Issue #3411241: Expand ConverterCommand documentation to make
it easier to run
---
scripts/src/ConverterCommand.php | 38 +++++++++++++++++++++++++++++++-
1 file changed, 37 insertions(+), 1 deletion(-)
diff --git a/scripts/src/ConverterCommand.php b/scripts/src/ConverterCommand.php
index 5414896b72..6de85b53e5 100644
--- a/scripts/src/ConverterCommand.php
+++ b/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 {
--
GitLab