chore: test that @deprecated items have version numbers (#9981)

* chore: test that `@deprecated` items have version numbers

* Add guidance on deprecations

* Apply patches

Co-authored-by: neznaika0 <ozornick.ks@gmail.com>

---------

Co-authored-by: neznaika0 <ozornick.ks@gmail.com>

Author: paulbalandan

contributing/internals.md

@@ -44,6 +44,31 @@ afraid to use it when it's needed and can help things.
 -   Start simple, refactor as necessary to achieve clean separation of
     code, but don't overdo it.
 
+## Deprecations
+
+Deprecations happen when code no longer fits its purpose or is superseded by better solutions.
+In such cases, it's important that deprecations are documented clearly to guide developers during
+their upgrade process.
+
+- Add `@deprecated` tags in the doc block of deprecated functions, methods, classes, etc. Include
+    the version number where the deprecation was introduced, a description of why it's deprecated,
+    and recommended replacement(s), if any. If there are multiple alternative approaches, list all of them.
+
+- Do not add `@deprecated` tags to a function/method if you only mean to deprecate its parameter(s).
+    This will cause the whole function/method to be marked as deprecated by IDEs. Instead, trigger
+    a deprecation inside the function/method body if those parameters are passed. Ensure to include
+    the version number since when the deprecation occurred. Optionally, but encouraged, add a `@todo`
+    comment so that it can be found later on.
+
+- User-facing deprecation warnings should also be triggered via the framework's deprecation handling
+    mechanism (e.g., `@trigger_error()` or error log entries) to alert end users.
+
+- Do not add new tests for deprecated code paths. Instead, use tools and static analysis to ensure
+    that no code within the framework or official packages is using the deprecated functionality.
+
+- Document all deprecations in the changelog file for that release, under a "Deprecations"
+    section, so users are informed when upgrading.
+
 ## Testing
 
 Any new packages submitted to the framework must be accompanied by unit

system/HTTP/Message.php

@@ -65,7 +65,7 @@ public function getBody()
      *
      * @return array<string, Header> An array of the request headers
      *
-     * @deprecated Use Message::headers() to make room for PSR-7
+     * @deprecated 4.0.5 Use Message::headers() to make room for PSR-7
      *
      * @TODO Incompatible return value with PSR-7
      *
@@ -82,7 +82,7 @@ public function getHeaders(): array
      *
      * @return array|Header|null
      *
-     * @deprecated Use Message::header() to make room for PSR-7
+     * @deprecated 4.0.5 Use Message::header() to make room for PSR-7
      *
      * @TODO Incompatible return value with PSR-7
      *

system/HTTP/OutgoingRequest.php

@@ -82,7 +82,7 @@ public function getMethod(): string
      *
      * @return $this
      *
-     * @deprecated Use withMethod() instead for immutability
+     * @deprecated 4.3.0 Use withMethod() instead for immutability
      */
     public function setMethod(string $method)
     {

system/HTTP/RequestTrait.php

@@ -39,7 +39,7 @@ trait RequestTrait
      *
      * @var string
      *
-     * @deprecated Will become private in a future release
+     * @deprecated 4.0.5 Will become private in a future release
      */
     protected $ipAddress = '';
 

system/HTTP/SiteURI.php

@@ -70,7 +70,7 @@ class SiteURI extends URI
      *
      * @var array<int, string>
      *
-     * @deprecated This property will be private.
+     * @deprecated 4.4.0 This property will be private.
      */
     protected $segments;
 
@@ -220,15 +220,15 @@ private function setBasePath(): void
     }
 
     /**
-     * @deprecated
+     * @deprecated 4.4.0
      */
     public function setBaseURL(string $baseURL): void
     {
         throw new BadMethodCallException('Cannot use this method.');
     }
 
     /**
-     * @deprecated
+     * @deprecated 4.4.0
      */
     public function setURI(?string $uri = null)
     {
@@ -312,7 +312,7 @@ private function convertToSegments(string $path): array
      *
      * @return $this
      *
-     * @deprecated This method will be private.
+     * @deprecated 4.4.0 This method will be private.
      */
     public function refreshPath()
     {

system/HTTP/URI.php

@@ -657,7 +657,7 @@ public function __toString(): string
      *
      * @return array{string, string}
      *
-     * @deprecated This method will be deleted.
+     * @deprecated 4.2.0 This method will be deleted.
      */
     private function changeSchemeAndPath(string $scheme, string $path): array
     {
@@ -840,7 +840,7 @@ public function setPath(string $path)
      *
      * @interal
      *
-     * @deprecated Use SiteURI instead.
+     * @deprecated 4.4.0 Use SiteURI instead.
      */
     public function setBaseURL(string $baseURL): void
     {
@@ -852,7 +852,7 @@ public function setBaseURL(string $baseURL): void
      *
      * @interal
      *
-     * @deprecated Use SiteURI instead.
+     * @deprecated 4.4.0 Use SiteURI instead.
      */
     public function getBaseURL(): string
     {
@@ -868,7 +868,7 @@ public function getBaseURL(): string
      *
      * @return $this
      *
-     * @deprecated This method will be private.
+     * @deprecated 4.4.0 This method will be private.
      */
     public function refreshPath()
     {

system/I18n/TimeLegacy.php

@@ -42,7 +42,7 @@
  *
  * @phpstan-consistent-constructor
  *
- * @deprecated Use Time instead.
+ * @deprecated 4.3.0 Use Time instead.
  * @see \CodeIgniter\I18n\TimeLegacyTest
  */
 class TimeLegacy extends DateTime

system/I18n/TimeTrait.php

@@ -292,7 +292,7 @@ public static function createFromInstance(DateTimeInterface $dateTime, ?string $
      *
      * @throws Exception
      *
-     * @deprecated         Use createFromInstance() instead
+     * @deprecated 4.3.0 Use createFromInstance() instead
      *
      * @codeCoverageIgnore
      */

system/Language/en/Email.php

@@ -34,6 +34,7 @@
     'SMTPAuthPassword'      => 'Failed to authenticate password. Error: {0}',
     'SMTPDataFailure'       => 'Unable to send data: {0}',
     'exitStatus'            => 'Exit status code: {0}',
-    // @deprecated
+
+    // @deprecated v4.7.0
     'failedSMTPLogin' => 'Failed to send AUTH LOGIN command. Error: {0}',
 ];

system/Language/en/HTTP.php

@@ -58,7 +58,7 @@
     'localeNotSupported' => 'Locale is not supported: {0}',
 
     // CSRF
-    // @deprecated use 'Security.disallowedAction'
+    // @deprecated 4.0.5 use 'Security.disallowedAction'
     'disallowedAction' => 'The action you requested is not allowed.',
 
     // Uploaded file moving