From 292b52c4c70aea8639a8aa1d33dc5e6a6fbe1dda Mon Sep 17 00:00:00 2001
From: "Eloy Lafuente (stronk7)" <stronk7@moodle.org>
Date: Sun, 4 Feb 2024 18:42:55 +0100
Subject: [PATCH] Add a few details towards phpcpd deprecation

- Add details to changelog.
- Emit a Symfony deprecation (but if running unit tests).
- Add a GH Workflow annotation to warn devs.

Note that, as a result of the changes in this commit,
code coverage will slightly decrease, because some
of the changes are unreachable when running unit tests,
but that's by design and on purpose, should be acceptable.
---
 docs/CHANGELOG.md                        |  5 +++++
 docs/CLI.md                              | 14 +++-----------
 phpunit.xml.dist                         |  3 +++
 src/Command/CopyPasteDetectorCommand.php | 18 ++++++++++++++++--
 4 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 5d97be41..01ec3260 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -9,10 +9,15 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 The format of this change log follows the advice given at [Keep a CHANGELOG](http://keepachangelog.com).
 
 ## [Unreleased]
+
 ### Changed
 - Updated all uses of `actions/checkout` from `v3` (using node 16) to `v4` (using node 20), because [actions using node 16 are deprecated](https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/) and will stop working in the future.
 * ACTION SUGGESTED: In order to avoid the node 16 deprecation warnings, update your workflows to use `actions/checkout@v4`.
 
+### Deprecated
+- The `phpcpd` command (that uses the [PHP Copy/Paste Detector](https://github.com/sebastianbergmann/phpcpd), now abandoned) has been deprecated in this `moodle-plugin-ci` release (4.4.0) and will be removed in 5.0.0. No replacement is planned.
+- ACTION SUGGESTED: In order to avoid deprecation warnings or annotations, proceed to remove this command from your workflows. Note that any use will throw an error in the next major release (5.0.0).
+
 ## [4.3.2] - 2024-01-26
 ### Changed
 - Modified internal CI scripts towards better Codecov future support.
diff --git a/docs/CLI.md b/docs/CLI.md
index 20a0ef9f..df8a3bb5 100644
--- a/docs/CLI.md
+++ b/docs/CLI.md
@@ -19,7 +19,7 @@ title: Moodle Plugin CI Commands
 * [`mustache`](#mustache)
 * [`parallel`](#parallel)
 * [`phpcbf`](#phpcbf)
-* [`phpcpd` (DEPRECATED)](#phpcpd)
+* [`phpcpd`](#phpcpd)
 * [`phpcs`](#phpcs)
 * [`phpdoc`](#phpdoc)
 * [`phplint`](#phplint)
@@ -1485,21 +1485,13 @@ Do not ask any interactive question
 `phpcpd`
 --------
 
-Run PHP Copy/Paste Detector on a plugin.
-
-### Deprecation Notice
-
-[PHP Copy/Paste Detector](https://github.com/sebastianbergmann/phpcpd) has been abandoned by its maintainers.
-
-The integration with it will be removed without replacement from future versions of this plugin.
-
-_Usage of the `phpcpd` command is discouraged._
+Run PHP Copy/Paste Detector on a plugin (**DEPRECATED**)
 
 ### Usage
 
 * `phpcpd <plugin>`
 
-Run PHP Copy/Paste Detector on a plugin
+Run PHP Copy/Paste Detector on a plugin (**DEPRECATED**)
 
 ### Arguments
 
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
index eb8d20bc..b32a19e0 100644
--- a/phpunit.xml.dist
+++ b/phpunit.xml.dist
@@ -11,4 +11,7 @@
       <directory suffix=".php">./src/</directory>
     </include>
   </coverage>
+  <php>
+    <const name="PHPUNIT_TEST" value="true"/>
+  </php>
 </phpunit>
diff --git a/src/Command/CopyPasteDetectorCommand.php b/src/Command/CopyPasteDetectorCommand.php
index 8d9b6e25..634d08fb 100644
--- a/src/Command/CopyPasteDetectorCommand.php
+++ b/src/Command/CopyPasteDetectorCommand.php
@@ -24,7 +24,7 @@
 /**
  * Run PHP Copy/Paste Detector on a plugin.
  *
- * @deprecated
+ * @deprecated Since 4.4.0, to be removed in 5.0.0. No replacement is planned.
  */
 class CopyPasteDetectorCommand extends AbstractPluginCommand
 {
@@ -33,11 +33,25 @@ protected function configure(): void
         parent::configure();
 
         $this->setName('phpcpd')
-            ->setDescription('Run PHP Copy/Paste Detector on a plugin (DEPRECATED)');
+            ->setDescription('Run PHP Copy/Paste Detector on a plugin (**DEPRECATED**)');
     }
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
+        if (!defined('PHPUNIT_TEST')) { // Only show deprecation warnings in non-test environments.
+            trigger_deprecation(
+                'moodle-plugin-ci',
+                '4,4,0',
+                'The "%s" command is deprecated and will be removed in %s. No replacement is planned.',
+                $this->getName(),
+                '5.0.0'
+            );
+            if (getenv('GITHUB_ACTIONS')) { // Only show deprecation annotations in GitHub Actions.
+                echo '::warning title=Deprecated command::The phpcpd command ' .
+                    'is deprecated and will be removed in 5.0.0. No replacement is planned.' . PHP_EOL;
+            }
+        }
+
         $timer = new Timer();
         $timer->start();