document compatibility workarounds

Dockerfile

@@ -1,5 +1,7 @@
 FROM composer:2.8 AS composer
 
+# TODO(compat): Replace PHP 7.4 with a supported PHP release once Laravel and
+# Composer dependencies support it; verify composer install and `just test`.
 FROM php:7.4-cli
 
 RUN apt-get update \

README.md

@@ -103,6 +103,15 @@ database; its temporary data is discarded when the container stops.
 This project uses several old dependencies, so a few small compatibility fixes
 are included:
 
+Temporary workarounds and legacy runtime pins are marked `TODO(compat)` in the
+source, with the condition for removing or replacing each one. Search for this
+marker during upgrades. In particular, remove the test `artisan()` override once
+Laravel's inherited helper works, and remove both the package-manifest patch
+and its Composer hook once Laravel supports Composer 2 directly.
+
+The test startup timestamp, isolated database settings, and database safety
+check are normal test infrastructure, not temporary version workarounds.
+
 - `phpdocumentor/phpdocumentor` 2.* was removed from `require-dev`. It requires
   Symfony 2.x, conflicts with Laravel 5.6, and was never present in
   `composer.lock`.

app/Providers/AppServiceProvider.php

@@ -20,7 +20,9 @@ class AppServiceProvider extends ServiceProvider
             return new CustomValidator($translator, $data, $rules, $messages);
         });
 
-        // Set default string length in order to run on older versions of MySQL
+        // TODO(compat): This limits strings to 191 characters for older MySQL
+        // utf8mb4 index limits. Remove once every supported database handles
+        // indexed 255-character utf8mb4 strings; verify fresh migrations first.
         Schema::defaultStringLength(191);
     }
 

compose.yaml

@@ -25,6 +25,8 @@ services:
     command: php artisan serve --host=0.0.0.0 --port=8000
 
   db:
+    # TODO(compat): Upgrade MySQL 5.7 after validating a restored data copy,
+    # migrations and reports. Update db-test to the same target version.
     image: mysql:5.7
     environment:
       MYSQL_DATABASE: pollux
@@ -42,6 +44,8 @@ services:
       retries: 20
 
   db-test:
+    # TODO(compat): Replace this legacy image alongside db during the MySQL
+    # upgrade; keep the test database isolated and run the full test suite.
     image: mysql:5.7
     profiles: [testing]
     environment:

mise.toml

@@ -1,5 +1,7 @@
 [tools]
 # Old Laravel Mix 2 / node-sass toolchain; use Node 10 for asset builds.
+# TODO(compat): Replace this pin with a supported Node LTS when Mix 2 and
+# node-sass are replaced; verify development and production asset builds.
 node = "10.24.1"
 just = "1.59.0"
 

scripts/patch-package-manifest.php

@@ -7,6 +7,11 @@
  *
  * This script adds support for both formats to the vendored framework file.
  * Composer runs it before package:discover, so it is safe to run repeatedly.
+ *
+ * TODO(compat): Once the upgraded Laravel supports Composer 2's installed
+ * package format itself, delete this script AND its post-autoload-dump entry
+ * in composer.json. Verify composer install and artisan package:discover
+ * succeed with a clean vendor directory and without this patch.
  */
 
 $file = __DIR__.'/../vendor/laravel/framework/src/Illuminate/Foundation/PackageManifest.php';

tests/DatabaseTestCase.php

@@ -28,9 +28,11 @@ abstract class DatabaseTestCase extends TestCase
 
     public function artisan($command, $parameters = [])
     {
-        // Laravel 5.6's Kernel::call uses a numeric command key, which the
+        // TODO(compat): Laravel 5.6's Kernel::call uses a numeric command key, which the
         // locked Symfony Console reads as a string offset on PHP 7.4.
-        // Use its normal input handler with a named command until upgraded.
+        // After upgrading Laravel/Symfony, remove this entire override and its
+        // Kernel, ArrayInput and BufferedOutput imports once `just test` passes
+        // using Laravel's inherited artisan() helper.
         $output = new BufferedOutput;
         $status = $this->app[Kernel::class]->handle(
             new ArrayInput(array_merge(['command' => $command], $parameters)), $output