Skip to content

Commit

Permalink
chore: better identify EXPERIMENTAL rules (#7729)
Browse files Browse the repository at this point in the history
Co-authored-by: Greg Korba <wirone@gmail.com>
  • Loading branch information
keradus and Wirone committed Jan 15, 2024
1 parent b03d0c4 commit 07af7f2
Show file tree
Hide file tree
Showing 13 changed files with 126 additions and 46 deletions.
21 changes: 14 additions & 7 deletions doc/rules/function_notation/phpdoc_to_param_type.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,27 @@
Rule ``phpdoc_to_param_type``
=============================

EXPERIMENTAL: Takes ``@param`` annotations of non-mixed types and adjusts
accordingly the function signature. Requires PHP >= 7.0.
Takes ``@param`` annotations of non-mixed types and adjusts accordingly the
function signature. Requires PHP >= 7.0.

Warning
-------

This rule is experimental
~~~~~~~~~~~~~~~~~~~~~~~~~

Rule is not covered with backward compatibility promise, use it at your own
risk. Rule's behaviour may be changed at any point, including rule's name; its
options' names, availability and allowed values; its default configuration. Rule
may be even removed without prior notice. Feel free to provide feedback and help
with determining final state of the rule.

Using this rule is risky
~~~~~~~~~~~~~~~~~~~~~~~~

This rule is EXPERIMENTAL and [1] is not covered with backward compatibility
promise. [2] ``@param`` annotation is mandatory for the fixer to make changes,
signatures of methods without it (no docblock, inheritdocs) will not be fixed.
[3] Manual actions are required if inherited signatures are not properly
documented.
The ``@param`` annotation is mandatory for the fixer to make changes, signatures
of methods without it (no docblock, inheritdocs) will not be fixed. Manual
actions are required if inherited signatures are not properly documented.

Configuration
-------------
Expand Down
21 changes: 14 additions & 7 deletions doc/rules/function_notation/phpdoc_to_property_type.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,27 @@
Rule ``phpdoc_to_property_type``
================================

EXPERIMENTAL: Takes ``@var`` annotation of non-mixed types and adjusts
accordingly the property signature. Requires PHP >= 7.4.
Takes ``@var`` annotation of non-mixed types and adjusts accordingly the
property signature. Requires PHP >= 7.4.

Warning
-------

This rule is experimental
~~~~~~~~~~~~~~~~~~~~~~~~~

Rule is not covered with backward compatibility promise, use it at your own
risk. Rule's behaviour may be changed at any point, including rule's name; its
options' names, availability and allowed values; its default configuration. Rule
may be even removed without prior notice. Feel free to provide feedback and help
with determining final state of the rule.

Using this rule is risky
~~~~~~~~~~~~~~~~~~~~~~~~

This rule is EXPERIMENTAL and [1] is not covered with backward compatibility
promise. [2] ``@var`` annotation is mandatory for the fixer to make changes,
signatures of properties without it (no docblock) will not be fixed. [3] Manual
actions might be required for newly typed properties that are read before
initialization.
The ``@var`` annotation is mandatory for the fixer to make changes, signatures
of properties without it (no docblock) will not be fixed. Manual actions might
be required for newly typed properties that are read before initialization.

Configuration
-------------
Expand Down
19 changes: 13 additions & 6 deletions doc/rules/function_notation/phpdoc_to_return_type.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,27 @@
Rule ``phpdoc_to_return_type``
==============================

EXPERIMENTAL: Takes ``@return`` annotation of non-mixed types and adjusts
accordingly the function signature.
Takes ``@return`` annotation of non-mixed types and adjusts accordingly the
function signature.

Warning
-------

This rule is experimental
~~~~~~~~~~~~~~~~~~~~~~~~~

Rule is not covered with backward compatibility promise, use it at your own
risk. Rule's behaviour may be changed at any point, including rule's name; its
options' names, availability and allowed values; its default configuration. Rule
may be even removed without prior notice. Feel free to provide feedback and help
with determining final state of the rule.

Using this rule is risky
~~~~~~~~~~~~~~~~~~~~~~~~

This rule is EXPERIMENTAL and [1] is not covered with backward compatibility
promise. [2] ``@return`` annotation is mandatory for the fixer to make changes,
The ``@return`` annotation is mandatory for the fixer to make changes,
signatures of methods without it (no docblock, inheritdocs) will not be fixed.
[3] Manual actions are required if inherited signatures are not properly
documented.
Manual actions are required if inherited signatures are not properly documented.

Configuration
-------------
Expand Down
16 changes: 8 additions & 8 deletions doc/rules/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -401,15 +401,15 @@ Function Notation
- `nullable_type_declaration_for_default_null_value <./function_notation/nullable_type_declaration_for_default_null_value.rst>`_

Adds or removes ``?`` before single type declarations or ``|null`` at the end of union types when parameters have a default ``null`` value.
- `phpdoc_to_param_type <./function_notation/phpdoc_to_param_type.rst>`_ *(risky)*
- `phpdoc_to_param_type <./function_notation/phpdoc_to_param_type.rst>`_ *(experimental, risky)*

EXPERIMENTAL: Takes ``@param`` annotations of non-mixed types and adjusts accordingly the function signature. Requires PHP >= 7.0.
- `phpdoc_to_property_type <./function_notation/phpdoc_to_property_type.rst>`_ *(risky)*
Takes ``@param`` annotations of non-mixed types and adjusts accordingly the function signature. Requires PHP >= 7.0.
- `phpdoc_to_property_type <./function_notation/phpdoc_to_property_type.rst>`_ *(experimental, risky)*

EXPERIMENTAL: Takes ``@var`` annotation of non-mixed types and adjusts accordingly the property signature. Requires PHP >= 7.4.
- `phpdoc_to_return_type <./function_notation/phpdoc_to_return_type.rst>`_ *(risky)*
Takes ``@var`` annotation of non-mixed types and adjusts accordingly the property signature. Requires PHP >= 7.4.
- `phpdoc_to_return_type <./function_notation/phpdoc_to_return_type.rst>`_ *(experimental, risky)*

EXPERIMENTAL: Takes ``@return`` annotation of non-mixed types and adjusts accordingly the function signature.
Takes ``@return`` annotation of non-mixed types and adjusts accordingly the function signature.
- `regular_callable_call <./function_notation/regular_callable_call.rst>`_ *(risky)*

Callables must be called without using ``call_user_func*`` when possible.
Expand Down Expand Up @@ -463,9 +463,9 @@ Import
Language Construct
------------------

- `class_keyword <./language_construct/class_keyword.rst>`_ *(risky)*
- `class_keyword <./language_construct/class_keyword.rst>`_ *(experimental, risky)*

EXPERIMENTAL: Converts FQCN strings to ``*::class`` keywords. Do not use it, unless you know what you are doing.
Converts FQCN strings to ``*::class`` keywords.
- `class_keyword_remove <./language_construct/class_keyword_remove.rst>`_ *(deprecated)*

Converts ``::class`` keywords to FQCN strings.
Expand Down
14 changes: 11 additions & 3 deletions doc/rules/language_construct/class_keyword.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@
Rule ``class_keyword``
======================

EXPERIMENTAL: Converts FQCN strings to ``*::class`` keywords. Do not use it,
unless you know what you are doing.
Converts FQCN strings to ``*::class`` keywords.

Description
-----------
Expand All @@ -16,10 +15,19 @@ context.
Warning
-------

This rule is experimental
~~~~~~~~~~~~~~~~~~~~~~~~~

Rule is not covered with backward compatibility promise, use it at your own
risk. Rule's behaviour may be changed at any point, including rule's name; its
options' names, availability and allowed values; its default configuration. Rule
may be even removed without prior notice. Feel free to provide feedback and help
with determining final state of the rule.

Using this rule is risky
~~~~~~~~~~~~~~~~~~~~~~~~

Risky as EXPERIMENTAL.
Do not use it, unless you know what you are doing.

Examples
--------
Expand Down
10 changes: 9 additions & 1 deletion src/Console/Command/DescribeCommand.php
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
use PhpCsFixer\Documentation\FixerDocumentGenerator;
use PhpCsFixer\Fixer\ConfigurableFixerInterface;
use PhpCsFixer\Fixer\DeprecatedFixerInterface;
use PhpCsFixer\Fixer\ExperimentalFixerInterface;
use PhpCsFixer\Fixer\FixerInterface;
use PhpCsFixer\FixerConfiguration\AliasedFixerOption;
use PhpCsFixer\FixerConfiguration\AllowedValueSubset;
Expand Down Expand Up @@ -179,8 +180,15 @@ private function describeRule(OutputInterface $output, string $name): void

$output->writeln('');

if ($fixer instanceof ExperimentalFixerInterface) {
$output->writeln('<error>Fixer applying this rule is EXPERIMENTAL.</error>.');
$output->writeln('It is not covered with backward compatibility promise and may produce unstable or unexpected results.');

$output->writeln('');
}

if ($fixer->isRisky()) {
$output->writeln('<error>Fixer applying this rule is risky.</error>');
$output->writeln('<error>Fixer applying this rule is RISKY.</error>');

$riskyDescription = $definition->getRiskyDescription();

Expand Down
19 changes: 19 additions & 0 deletions src/Documentation/FixerDocumentGenerator.php
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
use PhpCsFixer\Differ\FullDiffer;
use PhpCsFixer\Fixer\ConfigurableFixerInterface;
use PhpCsFixer\Fixer\DeprecatedFixerInterface;
use PhpCsFixer\Fixer\ExperimentalFixerInterface;
use PhpCsFixer\Fixer\FixerInterface;
use PhpCsFixer\FixerConfiguration\AliasedFixerOption;
use PhpCsFixer\FixerConfiguration\AllowedValueSubset;
Expand Down Expand Up @@ -89,6 +90,19 @@ public function generateFixerDocumentation(FixerInterface $fixer): string
}
}

$experimentalDescription = '';

if ($fixer instanceof ExperimentalFixerInterface) {
$experimentalDescriptionRaw = RstUtils::toRst('Rule is not covered with backward compatibility promise, use it at your own risk. Rule\'s behaviour may be changed at any point, including rule\'s name; its options\' names, availability and allowed values; its default configuration. Rule may be even removed without prior notice. Feel free to provide feedback and help with determining final state of the rule.', 0);
$experimentalDescription = <<<RST
This rule is experimental
~~~~~~~~~~~~~~~~~~~~~~~~~
{$experimentalDescriptionRaw}
RST;
}

$riskyDescription = '';
$riskyDescriptionRaw = $definition->getRiskyDescription();

Expand All @@ -115,6 +129,7 @@ public function generateFixerDocumentation(FixerInterface $fixer): string
$warningsHeader,
$warningsHeaderLine,
$deprecationDescription,
$experimentalDescription,
$riskyDescription,
]));
}
Expand Down Expand Up @@ -317,6 +332,10 @@ public function generateFixersDocumentationIndex(array $fixers): string
$attributes[] = 'deprecated';
}

if ($fixer instanceof ExperimentalFixerInterface) {
$attributes[] = 'experimental';
}

if ($fixer->isRisky()) {
$attributes[] = 'risky';
}
Expand Down
20 changes: 20 additions & 0 deletions src/Fixer/ExperimentalFixerInterface.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
<?php

declare(strict_types=1);

/*
* This file is part of PHP CS Fixer.
*
* (c) Fabien Potencier <fabien@symfony.com>
* Dariusz Rumiński <dariusz.ruminski@gmail.com>
*
* This source file is subject to the MIT license that is bundled
* with this source code in the file LICENSE.
*/

namespace PhpCsFixer\Fixer;

/**
* @internal
*/
interface ExperimentalFixerInterface extends FixerInterface {}
7 changes: 4 additions & 3 deletions src/Fixer/FunctionNotation/PhpdocToParamTypeFixer.php
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

use PhpCsFixer\AbstractPhpdocToTypeDeclarationFixer;
use PhpCsFixer\DocBlock\Annotation;
use PhpCsFixer\Fixer\ExperimentalFixerInterface;
use PhpCsFixer\FixerDefinition\CodeSample;
use PhpCsFixer\FixerDefinition\FixerDefinition;
use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
Expand All @@ -25,7 +26,7 @@
/**
* @author Jan Gantzert <jan@familie-gantzert.de>
*/
final class PhpdocToParamTypeFixer extends AbstractPhpdocToTypeDeclarationFixer
final class PhpdocToParamTypeFixer extends AbstractPhpdocToTypeDeclarationFixer implements ExperimentalFixerInterface
{
private const TYPE_CHECK_TEMPLATE = '<?php function f(%s $x) {}';

Expand All @@ -49,7 +50,7 @@ final class PhpdocToParamTypeFixer extends AbstractPhpdocToTypeDeclarationFixer
public function getDefinition(): FixerDefinitionInterface
{
return new FixerDefinition(
'EXPERIMENTAL: Takes `@param` annotations of non-mixed types and adjusts accordingly the function signature. Requires PHP >= 7.0.',
'Takes `@param` annotations of non-mixed types and adjusts accordingly the function signature. Requires PHP >= 7.0.',
[
new CodeSample(
'<?php
Expand Down Expand Up @@ -84,7 +85,7 @@ function bar($foo) {}
),
],
null,
'This rule is EXPERIMENTAL and [1] is not covered with backward compatibility promise. [2] `@param` annotation is mandatory for the fixer to make changes, signatures of methods without it (no docblock, inheritdocs) will not be fixed. [3] Manual actions are required if inherited signatures are not properly documented.'
'The `@param` annotation is mandatory for the fixer to make changes, signatures of methods without it (no docblock, inheritdocs) will not be fixed. Manual actions are required if inherited signatures are not properly documented.'
);
}

Expand Down
7 changes: 4 additions & 3 deletions src/Fixer/FunctionNotation/PhpdocToPropertyTypeFixer.php
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

use PhpCsFixer\AbstractPhpdocToTypeDeclarationFixer;
use PhpCsFixer\DocBlock\Annotation;
use PhpCsFixer\Fixer\ExperimentalFixerInterface;
use PhpCsFixer\FixerDefinition\CodeSample;
use PhpCsFixer\FixerDefinition\FixerDefinition;
use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
Expand All @@ -25,7 +26,7 @@
/**
* @phpstan-import-type _CommonTypeInfo from AbstractPhpdocToTypeDeclarationFixer
*/
final class PhpdocToPropertyTypeFixer extends AbstractPhpdocToTypeDeclarationFixer
final class PhpdocToPropertyTypeFixer extends AbstractPhpdocToTypeDeclarationFixer implements ExperimentalFixerInterface
{
private const TYPE_CHECK_TEMPLATE = '<?php class A { private %s $b; }';

Expand All @@ -40,7 +41,7 @@ final class PhpdocToPropertyTypeFixer extends AbstractPhpdocToTypeDeclarationFix
public function getDefinition(): FixerDefinitionInterface
{
return new FixerDefinition(
'EXPERIMENTAL: Takes `@var` annotation of non-mixed types and adjusts accordingly the property signature. Requires PHP >= 7.4.',
'Takes `@var` annotation of non-mixed types and adjusts accordingly the property signature. Requires PHP >= 7.4.',
[
new CodeSample(
'<?php
Expand Down Expand Up @@ -76,7 +77,7 @@ class Foo {
),
],
null,
'This rule is EXPERIMENTAL and [1] is not covered with backward compatibility promise. [2] `@var` annotation is mandatory for the fixer to make changes, signatures of properties without it (no docblock) will not be fixed. [3] Manual actions might be required for newly typed properties that are read before initialization.'
'The `@var` annotation is mandatory for the fixer to make changes, signatures of properties without it (no docblock) will not be fixed. Manual actions might be required for newly typed properties that are read before initialization.'
);
}

Expand Down
7 changes: 4 additions & 3 deletions src/Fixer/FunctionNotation/PhpdocToReturnTypeFixer.php
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
namespace PhpCsFixer\Fixer\FunctionNotation;

use PhpCsFixer\AbstractPhpdocToTypeDeclarationFixer;
use PhpCsFixer\Fixer\ExperimentalFixerInterface;
use PhpCsFixer\FixerDefinition\CodeSample;
use PhpCsFixer\FixerDefinition\FixerDefinition;
use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
Expand All @@ -27,7 +28,7 @@
/**
* @author Filippo Tessarotto <zoeslam@gmail.com>
*/
final class PhpdocToReturnTypeFixer extends AbstractPhpdocToTypeDeclarationFixer
final class PhpdocToReturnTypeFixer extends AbstractPhpdocToTypeDeclarationFixer implements ExperimentalFixerInterface
{
private const TYPE_CHECK_TEMPLATE = '<?php function f(): %s {}';

Expand All @@ -51,7 +52,7 @@ final class PhpdocToReturnTypeFixer extends AbstractPhpdocToTypeDeclarationFixer
public function getDefinition(): FixerDefinitionInterface
{
return new FixerDefinition(
'EXPERIMENTAL: Takes `@return` annotation of non-mixed types and adjusts accordingly the function signature.',
'Takes `@return` annotation of non-mixed types and adjusts accordingly the function signature.',
[
new CodeSample(
'<?php
Expand Down Expand Up @@ -104,7 +105,7 @@ public function create($prototype) {
),
],
null,
'This rule is EXPERIMENTAL and [1] is not covered with backward compatibility promise. [2] `@return` annotation is mandatory for the fixer to make changes, signatures of methods without it (no docblock, inheritdocs) will not be fixed. [3] Manual actions are required if inherited signatures are not properly documented.'
'The `@return` annotation is mandatory for the fixer to make changes, signatures of methods without it (no docblock, inheritdocs) will not be fixed. Manual actions are required if inherited signatures are not properly documented.'
);
}

Expand Down
7 changes: 4 additions & 3 deletions src/Fixer/LanguageConstruct/ClassKeywordFixer.php
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
namespace PhpCsFixer\Fixer\LanguageConstruct;

use PhpCsFixer\AbstractFixer;
use PhpCsFixer\Fixer\ExperimentalFixerInterface;
use PhpCsFixer\FixerDefinition\CodeSample;
use PhpCsFixer\FixerDefinition\FixerDefinition;
use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
Expand All @@ -23,12 +24,12 @@
/**
* @author Dariusz Rumiński <dariusz.ruminski@gmail.com>
*/
final class ClassKeywordFixer extends AbstractFixer
final class ClassKeywordFixer extends AbstractFixer implements ExperimentalFixerInterface
{
public function getDefinition(): FixerDefinitionInterface
{
return new FixerDefinition(
'EXPERIMENTAL: Converts FQCN strings to `*::class` keywords. Do not use it, unless you know what you are doing.',
'Converts FQCN strings to `*::class` keywords.',
[
new CodeSample(
'<?php
Expand All @@ -39,7 +40,7 @@ public function getDefinition(): FixerDefinitionInterface
),
],
'This rule does not have an understanding of whether a class exists in the scope of the codebase or not, relying on run-time and autoloaded classes to determine it, which makes the rule useless when running on a single file out of codebase context.',
'Risky as EXPERIMENTAL.'
'Do not use it, unless you know what you are doing.'
);
}

Expand Down
Loading

0 comments on commit 07af7f2

Please sign in to comment.