chore: update docs to use Attributes instead of Annotations #178

carlos-granados · 2024-11-29T15:31:45Z

Updates all documentation to use PHP attributes instead of doc-block annotations
Adds a new section that explains the use of annotations

This should not be merged yet, I would like to wait for two things:

This PR which changes the snippets to use attributes instead of annotations and which also updates all our tests
Rector 2.0 to be released, which includes the rule that allow you to automatically convert your annotations to attributes

Closes #177

stof · 2024-11-29T16:29:26Z

I don't think the Rector 2.0 release is a blocker for updating our documentation (it is a blocker for deprecating annotations as we want to make Rector the migration tool)

carlos-granados · 2024-11-29T16:35:23Z

I don't think the Rector 2.0 release is a blocker for updating our documentation (it is a blocker for deprecating annotations as we want to make Rector the migration tool)

Yeah, if we agree this is ready before Rector is ready, we can release these changes without the mention to Rector, let's see

acoulton

LGTM, a couple of small suggestions. Thanks!

acoulton · 2024-12-01T22:54:35Z

quick_start.rst

+    Behat uses PHP Attributes for step definitions, step
+    transformations and hooks. It can also use doc-block annotations
+    and this will be described in the User Guide


Maybe more like this, with a link to the new page?

Behat uses PHP Attributes for step definitions, step
transformations and hooks. It also supports doc-block
annotations for compatibility with legacy code, but this
syntax is deprecated - see the annotations documentation
for details.

acoulton · 2024-12-01T22:58:54Z

quick_start.rst

 looks like ``... there is a ..., which costs £...``. This pattern will match
 any of the following steps:


Maybe we should make it even more explicit that #[Given] / #[When] / #[Then] are completely interchangeable? This section does already say the pattern will match any of the following steps but I think with attributes it's even more surprising that we have 3 attributes that do the same thing...?

Do you think you might suggest a text for this?

Suggested change

looks like ``... there is a ..., which costs £...``. This pattern will match

any of the following steps:

looks like ``... there is a ..., which costs £...``.

The ``#[Given]``, ``#[When]`` and ``#[Then]`` attributes are functionally identical - they

only exist separately to help keep the wording of your step definitions readable. So

this pattern will match any of the following steps:

acoulton · 2024-12-01T23:00:54Z

quick_start.rst

+    Also, Behat will not add the ``use`` statements for the step attributes for you, you
+    may need to add them manually if they were not yet present in your context.


How hard would it be to make it that it does? If that's too hard, should we generate attributes with FQCN and it's up to the user to shorten them if they want?

I can see it tripping a lot of people up if their file looks right but it's not matching anything because they've not noticed they need to import the attributes...

I have added an issue to our Behat repo to handle this. Until this issue is done we can keep this comment here. The issue is: Behat/Behat#1553

I think this is now going to be solved in Behat/Behat#1549 so we can probably take it out?

acoulton · 2024-12-01T23:03:07Z

user_guide/annotations.rst

+transformations in PHP contexts. These annotations are still available and you can use them instead
+of PHP attributes in your projects.


I think we should be more forceful here.

Suggested change

transformations in PHP contexts. These annotations are still available and you can use them instead

of PHP attributes in your projects.

transformations in PHP contexts. These annotations are still available for now, and you can use them instead

of PHP attributes in your projects - however they will likely be deprecated and removed in the future.

acoulton · 2024-12-01T23:04:58Z

user_guide/annotations.rst

+         * @When event occurs
+         */
+        public function doSomeAction()


Maybe worth showing with a parameter, so people can more easily see it's the same as an attribute?

Suggested change

* @When event occurs

*/

public function doSomeAction()

* @When an :event occurs

*/

public function onEvent(string $event)

acoulton · 2024-12-01T23:05:56Z

user_guide/annotations.rst

+-------------
+
+Even though annotations are still available, they will probably be deprecated and eventually removed in the future.
+In this way, for new projects we recommend that you don't use them. If your current project uses annotations, we


Suggested change

In this way, for new projects we recommend that you don't use them. If your current project uses annotations, we

Therefore, we do not recommend using annotations for new projects. If your current project uses annotations, we

acoulton · 2024-12-01T23:10:26Z

user_guide/annotations.rst

+recommend that you refactor your code to use PHP attributes instead. This can be done manually but you should be able
+to use the search and replace capabilities of your IDE to do this in a more automated way.
+
+Alternatively you may want to use a tool like `Rector`_ which can do automated refactoring of your code. Rector includes


I think you could just say Rector 2.0 includes a rule... even if this is ready before the release is out. That's enough for people to work out whether to try it with an RC / wait for it IMO and saves waiting or coming back to this later.

acoulton

Looks great, suggested wording for the interchangeable attributes as requested.

acoulton · 2024-12-06T09:30:08Z

quick_start.rst

+    Also, Behat will not add the ``use`` statements for the step attributes for you, you
+    may need to add them manually if they were not yet present in your context.


I think this is now going to be solved in Behat/Behat#1549 so we can probably take it out?

acoulton · 2024-12-06T09:36:16Z

quick_start.rst

 looks like ``... there is a ..., which costs £...``. This pattern will match
 any of the following steps:


Suggested change

looks like ``... there is a ..., which costs £...``. This pattern will match

any of the following steps:

looks like ``... there is a ..., which costs £...``.

The ``#[Given]``, ``#[When]`` and ``#[Then]`` attributes are functionally identical - they

only exist separately to help keep the wording of your step definitions readable. So

this pattern will match any of the following steps:

acoulton

Great :)

carlos-granados mentioned this pull request Nov 29, 2024

Attributes in documentation #177

Closed

acoulton requested changes Dec 1, 2024

View reviewed changes

carlos-granados mentioned this pull request Dec 4, 2024

PHP Config - Suites #179

Merged

acoulton reviewed Dec 6, 2024

View reviewed changes

chore: update docs to use Attributes instead of Annotations

738b879

carlos-granados force-pushed the attributes-instead-of-annotations branch from 1445acf to 738b879 Compare December 7, 2024 20:57

carlos-granados marked this pull request as ready for review December 7, 2024 20:57

carlos-granados requested a review from acoulton December 7, 2024 20:58

acoulton approved these changes Dec 9, 2024

View reviewed changes

acoulton merged commit 21caa65 into Behat:v3.0 Dec 9, 2024
4 checks passed

carlos-granados deleted the attributes-instead-of-annotations branch December 9, 2024 09:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: update docs to use Attributes instead of Annotations #178

chore: update docs to use Attributes instead of Annotations #178

carlos-granados commented Nov 29, 2024

stof commented Nov 29, 2024

carlos-granados commented Nov 29, 2024

acoulton left a comment

acoulton Dec 1, 2024

carlos-granados Dec 2, 2024

acoulton Dec 1, 2024

carlos-granados Dec 2, 2024

acoulton Dec 6, 2024

acoulton Dec 1, 2024

carlos-granados Dec 2, 2024

acoulton Dec 6, 2024

acoulton Dec 1, 2024

carlos-granados Dec 2, 2024

acoulton Dec 1, 2024

carlos-granados Dec 2, 2024

acoulton Dec 1, 2024

carlos-granados Dec 2, 2024

acoulton Dec 1, 2024

carlos-granados Dec 2, 2024

acoulton left a comment

acoulton Dec 6, 2024

acoulton Dec 6, 2024

acoulton left a comment

		looks like ``... there is a ..., which costs £...``. This pattern will match
		any of the following steps:

		Also, Behat will not add the ``use`` statements for the step attributes for you, you
		may need to add them manually if they were not yet present in your context.

		transformations in PHP contexts. These annotations are still available and you can use them instead
		of PHP attributes in your projects.

	In this way, for new projects we recommend that you don't use them. If your current project uses annotations, we
	Therefore, we do not recommend using annotations for new projects. If your current project uses annotations, we

chore: update docs to use Attributes instead of Annotations #178

chore: update docs to use Attributes instead of Annotations #178

Conversation

carlos-granados commented Nov 29, 2024

stof commented Nov 29, 2024

carlos-granados commented Nov 29, 2024

acoulton left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

acoulton left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

acoulton left a comment

Choose a reason for hiding this comment