Skip to content

Commit 07fa170

Browse files
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>
1 parent 75ab812 commit 07fa170

File tree

17 files changed

+145
-47
lines changed

17 files changed

+145
-47
lines changed

contributing/internals.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,31 @@ afraid to use it when it's needed and can help things.
4444
- Start simple, refactor as necessary to achieve clean separation of
4545
code, but don't overdo it.
4646

47+
## Deprecations
48+
49+
Deprecations happen when code no longer fits its purpose or is superseded by better solutions.
50+
In such cases, it's important that deprecations are documented clearly to guide developers during
51+
their upgrade process.
52+
53+
- Add `@deprecated` tags in the doc block of deprecated functions, methods, classes, etc. Include
54+
the version number where the deprecation was introduced, a description of why it's deprecated,
55+
and recommended replacement(s), if any. If there are multiple alternative approaches, list all of them.
56+
57+
- Do not add `@deprecated` tags to a function/method if you only mean to deprecate its parameter(s).
58+
This will cause the whole function/method to be marked as deprecated by IDEs. Instead, trigger
59+
a deprecation inside the function/method body if those parameters are passed. Ensure to include
60+
the version number since when the deprecation occurred. Optionally, but encouraged, add a `@todo`
61+
comment so that it can be found later on.
62+
63+
- User-facing deprecation warnings should also be triggered via the framework's deprecation handling
64+
mechanism (e.g., `@trigger_error()` or error log entries) to alert end users.
65+
66+
- Do not add new tests for deprecated code paths. Instead, use tools and static analysis to ensure
67+
that no code within the framework or official packages is using the deprecated functionality.
68+
69+
- Document all deprecations in the changelog file for that release, under a "Deprecations"
70+
section, so users are informed when upgrading.
71+
4772
## Testing
4873

4974
Any new packages submitted to the framework must be accompanied by unit

system/HTTP/Message.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ public function getBody()
6565
*
6666
* @return array<string, Header> An array of the request headers
6767
*
68-
* @deprecated Use Message::headers() to make room for PSR-7
68+
* @deprecated 4.0.5 Use Message::headers() to make room for PSR-7
6969
*
7070
* @TODO Incompatible return value with PSR-7
7171
*
@@ -82,7 +82,7 @@ public function getHeaders(): array
8282
*
8383
* @return array|Header|null
8484
*
85-
* @deprecated Use Message::header() to make room for PSR-7
85+
* @deprecated 4.0.5 Use Message::header() to make room for PSR-7
8686
*
8787
* @TODO Incompatible return value with PSR-7
8888
*

system/HTTP/OutgoingRequest.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ public function getMethod(): string
8282
*
8383
* @return $this
8484
*
85-
* @deprecated Use withMethod() instead for immutability
85+
* @deprecated 4.3.0 Use withMethod() instead for immutability
8686
*/
8787
public function setMethod(string $method)
8888
{

system/HTTP/RequestTrait.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ trait RequestTrait
3939
*
4040
* @var string
4141
*
42-
* @deprecated Will become private in a future release
42+
* @deprecated 4.0.5 Will become private in a future release
4343
*/
4444
protected $ipAddress = '';
4545

system/HTTP/SiteURI.php

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ class SiteURI extends URI
7070
*
7171
* @var array<int, string>
7272
*
73-
* @deprecated This property will be private.
73+
* @deprecated 4.4.0 This property will be private.
7474
*/
7575
protected $segments;
7676

@@ -220,15 +220,15 @@ private function setBasePath(): void
220220
}
221221

222222
/**
223-
* @deprecated
223+
* @deprecated 4.4.0
224224
*/
225225
public function setBaseURL(string $baseURL): void
226226
{
227227
throw new BadMethodCallException('Cannot use this method.');
228228
}
229229

230230
/**
231-
* @deprecated
231+
* @deprecated 4.4.0
232232
*/
233233
public function setURI(?string $uri = null)
234234
{
@@ -312,7 +312,7 @@ private function convertToSegments(string $path): array
312312
*
313313
* @return $this
314314
*
315-
* @deprecated This method will be private.
315+
* @deprecated 4.4.0 This method will be private.
316316
*/
317317
public function refreshPath()
318318
{

system/HTTP/URI.php

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -657,7 +657,7 @@ public function __toString(): string
657657
*
658658
* @return array{string, string}
659659
*
660-
* @deprecated This method will be deleted.
660+
* @deprecated 4.2.0 This method will be deleted.
661661
*/
662662
private function changeSchemeAndPath(string $scheme, string $path): array
663663
{
@@ -840,7 +840,7 @@ public function setPath(string $path)
840840
*
841841
* @interal
842842
*
843-
* @deprecated Use SiteURI instead.
843+
* @deprecated 4.4.0 Use SiteURI instead.
844844
*/
845845
public function setBaseURL(string $baseURL): void
846846
{
@@ -852,7 +852,7 @@ public function setBaseURL(string $baseURL): void
852852
*
853853
* @interal
854854
*
855-
* @deprecated Use SiteURI instead.
855+
* @deprecated 4.4.0 Use SiteURI instead.
856856
*/
857857
public function getBaseURL(): string
858858
{
@@ -868,7 +868,7 @@ public function getBaseURL(): string
868868
*
869869
* @return $this
870870
*
871-
* @deprecated This method will be private.
871+
* @deprecated 4.4.0 This method will be private.
872872
*/
873873
public function refreshPath()
874874
{

system/I18n/TimeLegacy.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
*
4343
* @phpstan-consistent-constructor
4444
*
45-
* @deprecated Use Time instead.
45+
* @deprecated 4.3.0 Use Time instead.
4646
* @see \CodeIgniter\I18n\TimeLegacyTest
4747
*/
4848
class TimeLegacy extends DateTime

system/I18n/TimeTrait.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -292,7 +292,7 @@ public static function createFromInstance(DateTimeInterface $dateTime, ?string $
292292
*
293293
* @throws Exception
294294
*
295-
* @deprecated Use createFromInstance() instead
295+
* @deprecated 4.3.0 Use createFromInstance() instead
296296
*
297297
* @codeCoverageIgnore
298298
*/

system/Language/en/Email.php

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
'SMTPAuthPassword' => 'Failed to authenticate password. Error: {0}',
3535
'SMTPDataFailure' => 'Unable to send data: {0}',
3636
'exitStatus' => 'Exit status code: {0}',
37-
// @deprecated
37+
38+
// @deprecated v4.7.0
3839
'failedSMTPLogin' => 'Failed to send AUTH LOGIN command. Error: {0}',
3940
];

system/Language/en/HTTP.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@
5858
'localeNotSupported' => 'Locale is not supported: {0}',
5959

6060
// CSRF
61-
// @deprecated use 'Security.disallowedAction'
61+
// @deprecated 4.0.5 use 'Security.disallowedAction'
6262
'disallowedAction' => 'The action you requested is not allowed.',
6363

6464
// Uploaded file moving

0 commit comments

Comments
 (0)