From c4dd22ee296622ed7123890b8bd968092c5ee986 Mon Sep 17 00:00:00 2001
From: Nicolas Joubert <njoubert@clever-age.com>
Date: Fri, 6 Nov 2026 16:52:20 +0100
Subject: [PATCH] #503 - Deprecate ProcessState::getReturnCode() /
 setReturnCode(), used nowhere

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                     |  1 +
 UPGRADE.md                       |  6 ++++++
 src/Model/ProcessState.php       | 13 +++++++++++++
 tests/Model/ProcessStateTest.php | 23 +++++++++++++++++++++++
 4 files changed, 43 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 05707a5e..7f532ade 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@ Latest
 ------
 
 ## Changes
+* [#503](https://github.com/cleverage/process-bundle/issues/503) `ProcessState::getReturnCode()` / `setReturnCode()`, used nowhere, are deprecated (removed in 6.0). Add tests.
 * [#479](https://github.com/cleverage/process-bundle/issues/479) Performance: the `Processing task <task_code>` debug log is written at the first execution of each task by execution of its process, instead of for each item (a record was built for each item even when debug records are not handled: 100,000 lines through 3 tasks took 7.7 s of CPU instead of 2.3 s). Update documentation, add tests.
 * [#497](https://github.com/cleverage/process-bundle/issues/497) Documentation: the default error output of a task is `null` when the task has no input: a root task (except the `entry_point`), a failure of `proceed` or `flush`.
 * [#495](https://github.com/cleverage/process-bundle/issues/495) Documentation: `symfony/lock` (exclusive processes) in the optional packages of the quick start; in the good practices, `{date_time}` (one second resolution) does not make a file path unique, `{unique_token}` does.
diff --git a/UPGRADE.md b/UPGRADE.md
index 145fd79e..9ada31af 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -35,6 +35,12 @@ documented. The outputs of another root task, of a blocking task proceeded or of
 now go on through the tasks of the stopped flow: they were dropped silently by the first task that had stopped. Check
 the processes with several root tasks, or with a blocking task (e.g. `aggregate_iterable`) fed before a stop.
 
+### Return code of the process state
+
+`ProcessState::getReturnCode()` / `setReturnCode()` are deprecated since 5.10 (`Since cleverage/process-bundle 5.10: The
+"CleverAge\ProcessBundle\Model\ProcessState::setReturnCode()" method is deprecated...`) and will be removed in 6.0: they
+are used nowhere, the exit code of `cleverage:process:execute` does not depend on them. Remove their calls.
+
 ## v5.8
 
 ### Unknown task references
diff --git a/src/Model/ProcessState.php b/src/Model/ProcessState.php
index 26554175..a652eab8 100644
--- a/src/Model/ProcessState.php
+++ b/src/Model/ProcessState.php
@@ -60,6 +60,9 @@ class ProcessState
      */
     protected array $errorContext = [];
 
+    /**
+     * @deprecated since 5.10, used nowhere, will be removed in v6.0
+     */
     protected ?int $returnCode = null;
 
     protected bool $skipped;
@@ -235,13 +238,23 @@ public function removeErrorContext(string|int $key): void
         unset($this->errorContext[$key]);
     }
 
+    /**
+     * @deprecated since 5.10, used nowhere, will be removed in v6.0
+     */
     public function getReturnCode(): int
     {
+        trigger_deprecation('cleverage/process-bundle', '5.10', 'The "%s()" method is deprecated: it is used nowhere and will be removed in 6.0.', __METHOD__);
+
         return $this->returnCode ?? 0;
     }
 
+    /**
+     * @deprecated since 5.10, used nowhere (the exit code of the command does not depend on it), will be removed in v6.0
+     */
     public function setReturnCode(int $returnCode): void
     {
+        trigger_deprecation('cleverage/process-bundle', '5.10', 'The "%s()" method is deprecated: it is used nowhere (the exit code of the command does not depend on it) and will be removed in 6.0.', __METHOD__);
+
         $this->returnCode = $returnCode;
     }
 
diff --git a/tests/Model/ProcessStateTest.php b/tests/Model/ProcessStateTest.php
index 0fc69490..2aabf337 100644
--- a/tests/Model/ProcessStateTest.php
+++ b/tests/Model/ProcessStateTest.php
@@ -77,6 +77,29 @@ public function testContextualizedOptionsUseADefaultResolver(): void
         self::assertSame(['foo' => 'baz'], $state->getContextualizedOptions());
     }
 
+    public function testReturnCodeIsDeprecated(): void
+    {
+        $state = $this->createState();
+        $deprecations = [];
+        set_error_handler(static function (int $errno, string $errstr) use (&$deprecations): bool {
+            $deprecations[] = $errstr;
+
+            return true;
+        }, \E_USER_DEPRECATED);
+        try {
+            $state->setReturnCode(2);
+            $returnCode = $state->getReturnCode();
+        } finally {
+            restore_error_handler();
+        }
+
+        $this->assertSame(2, $returnCode);
+        $this->assertSame([
+            'Since cleverage/process-bundle 5.10: The "CleverAge\\ProcessBundle\\Model\\ProcessState::setReturnCode()" method is deprecated: it is used nowhere (the exit code of the command does not depend on it) and will be removed in 6.0.',
+            'Since cleverage/process-bundle 5.10: The "CleverAge\\ProcessBundle\\Model\\ProcessState::getReturnCode()" method is deprecated: it is used nowhere and will be removed in 6.0.',
+        ], $deprecations);
+    }
+
     private function createState(): ProcessState
     {
         $processConfiguration = new ProcessConfiguration('test', []);