docs: Add and update docs for the 4.0 release

cookbooks/custom_formatter.rst

@@ -150,7 +150,7 @@ etc.
        }
 
        /**
-        * setParameter will be called for each key given to the formatter in your behat.yml file.
+        * setParameter will be called for each key given to the formatter in your behat.php file.
         * We will see that later in the "integration".
         * In our case, the only allowed parameter is a "file_name" that must be a string : the JSON file that we will write.
         */
@@ -194,7 +194,7 @@ etc.
        }
 
        /**
-        * This is the name of the formatter, that will be used in the behat.yml file
+        * This is the name of the formatter, that will be used in the behat.php file
         */
        public function getName(): string
        {
@@ -508,4 +508,3 @@ About the author
 
 Written by `Julien Deniau <https://julien.deniau.me>`__,
 originally posted as a blog post `on his blog <https://julien.deniau.me/posts/2024-01-24-custom-behat-formatter>`__.
-

guides.rst

@@ -75,7 +75,6 @@ Documentation Contents
    user_guide/writing_scenarios
    user_guide/organizing
    user_guide/context
-   user_guide/annotations
    user_guide/command_line_tool
    user_guide/configuration
    user_guide/integrations

quick_start.rst

@@ -282,11 +282,10 @@ in our case) and tell Behat that this code represents a specific scenario step
 
 .. note::
 
-    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 :doc:`annotations </user_guide/annotations>` documentation
-    for details.
+    Behat uses PHP Attributes for step definitions, step transformations and hooks.
+    In Behat 4.0, we removed support for defining this with PHPDoc annotations.
+    You can automatically convert these to attributes - see
+    :doc:`the 4.0 upgrade guide </releases/upgrading-to-4.0>`.
 
 ``#[Given('there is a(n) :arg1, which costs £:arg2')]`` above the method tells Behat
 that this particular method should be executed whenever Behat sees step that

releases.rst

@@ -1,17 +1,19 @@
 Releases & version support
 ==========================
 
-Behat follows `Semantic Versioning`_ - breaking changes will only be made in a major release.
+Behat follows `Semantic Versioning`_ - therefore we will only make breaking changes to the Public API in a major
+release. Note that a significant portion of Behat's codebase is **not considered part of the Public API** - you
+can read more in :doc:`the Backward Compatibility documentation </releases/backwards-compatibility>`.
 
 Supported versions
 ------------------
 
-======= ========== ========== ============ =======================================================================
+======= ========== ========== ============ ====================================================================
 Major   Released   Bugfix EOL Security EOL
-======= ========== ========== ============ =======================================================================
+======= ========== ========== ============ ====================================================================
 `v3.x`_ April 2014 See below  See below    `Changelog <https://github.com/Behat/Behat/blob/3.x/CHANGELOG.md>`__
-`v4.x`_ tbc 2025/6 See below  See below    `Changelog <https://github.com/Behat/Behat/blob/4.x/CHANGELOG.md>`__
-======= ========== ========== ============ =======================================================================
+`v4.x`_ tbc Q3/26  See below  See below    `4.x Changelog`_ :doc:`Upgrading </releases/upgrading-to-4.0>`
+======= ========== ========== ============ ====================================================================
 
 As a minimum, a major version series will receive:
 
@@ -82,10 +84,19 @@ Major   Released   Bugfix EOL   Security EOL
 `v2.x`_ July 2011  June 2015    June 2015    `Changelog <https://github.com/Behat/Behat/blob/2.5/CHANGES.md>`__
 ======= ========== ============ ============ =====================================================================
 
+Additional Releases documentation
+---------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   releases/backwards-compatibility
+   releases/upgrading-to-4.0
 
 .. _`Semantic Versioning`: http://semver.org/
 .. _`official php.net version support page`: https://www.php.net/supported-versions.php
 .. _`official Symfony releases page`: https://symfony.com/releases
 .. _`v2.x`: https://github.com/Behat/Behat/releases?q=v2
 .. _`v3.x`: https://github.com/Behat/Behat/releases?q=v3
 .. _`v4.x`: https://github.com/Behat/Behat/releases?q=v4
+.. _`4.x Changelog`: https://github.com/Behat/Behat/blob/4.x/CHANGELOG.md

releases/backwards-compatibility.rst

@@ -0,0 +1,83 @@
+Backwards Compatibility and the Behat Public API
+================================================
+
+Behat follows Semantic Versioning. For minor or patch releases, we aim to keep things stable:
+
+* CLI arguments and options will stay the same. We may add new ones, but existing ones will continue to work as they do
+  now.
+* Configuration options will not change or be removed. New options may be added, and their default values will match
+  the previous behavior.
+* Machine-readable output (like JSON or JUnit) will keep the same fields and data types. We might add new fields or
+  change how text is formatted (like adding or removing whitespace), but the structure will remain compatible.
+* Any changes to the public API (interfaces, classes, and behavior) will be backwards-compatible with the previous
+  version.
+* Your code (step definitions, hooks, transformations) will run the same way between versions - including
+  that we will trigger hooks in the same order.
+* Behat's event dispatcher will fire the same events in the same order. We might add new events in between, but
+  existing ones will stay.
+
+The only time we might break this is to fix a critical bug or a security issue that cannot be resolved any other way.
+
+Note that from version 4.0 onwards, we do not guarantee the exact format of human-readable output (like the ``progress``
+or ``pretty`` formatters). These are intended for people to read, so we may improve them over time.
+
+What counts as Behat's "Public API"?
+------------------------------------
+
+Starting with version 3.30.0, all interfaces, classes, and methods in Behat are **internal by default**. We follow the
+`phpstan backwards compatibility convention`_, which means code is only part of our public API if it is explicitly
+marked with the ``@api`` tag.
+
+* In Behat 4.0 and later, our compatibility promise only applies to code marked with ``@api``. Anything else may change
+  in any release.
+* In Behat 3.x, we maintain compatibility for the entire codebase. However, if you are using code that is not
+  marked ``@api``, we recommend updating your code or asking us to make it public.
+
+.. note::
+
+    We are happy to consider making more of the Behat codebase public. If you need an ``@api`` tag added, please let
+    us know! We will look at your use case and see how it affects the long-term maintenance of Behat.
+
+    Please open an issue (or even better a Pull Request) with details on what you would like to use and why.
+
+Classes
+~~~~~~~
+
+* Only (non-final) classes with ``@api`` in their PHPDoc can be extended.
+* Objects can only be created via ``new`` if the PHPDoc of the
+  public constructor is directly tagged with ``@api``. In all other cases
+  (even if the class PHPDoc has ``@api``), instances of the class should
+  only be created by / retrieved from Behat's service container.
+* Methods can only be called if there is an ``@api`` tag in the PHPDoc
+  of the method, declaring class, or declaring interface.
+* Constants can only be accessed if there is an ``@api`` tag in the
+  PHPDoc of the constant, declaring class, or declaring interface.
+
+Interfaces
+~~~~~~~~~~
+
+* Interfaces with ``@api`` in their PHPDoc can be implemented and extended.
+* All methods from interfaces with ``@api`` in their PHPDoc can be called.
+
+Traits
+~~~~~~
+
+* No Behat traits can be used.
+
+
+Other tips for extension authors
+--------------------------------
+
+Our compatibility promise covers changes to existing code, but we will still add new features like CLI arguments,
+config options, or methods.
+
+To avoid conflicts with future versions of Behat, we recommend following these practices:
+
+* Do not use the ``Behat`` namespace for your own code.
+* Only add configuration options within your extension's own namespace.
+* While you can add new CLI commands or flags, it's safer to use configuration files or Behat's ``--profile`` feature.
+  This avoids naming conflicts with future Behat versions.
+* If you extend a Behat class (marked ``@api``), try to avoid adding new public methods. This protects you if Behat adds
+  a method with the same name in the future.
+
+.. _`phpstan backwards compatibility convention`: https://phpstan.org/developing-extensions/backward-compatibility-promise

releases/upgrading-to-4.0.rst

@@ -0,0 +1,107 @@
+Upgrading to Behat 4.0
+======================
+
+We want to make upgrading to Behat 4.0 as smooth as possible. While there are some breaking changes, we've tried to
+keep them to a minimum.
+
+If you are an end-user (meaning you use Behat to run tests but haven't written custom extensions), most of these changes
+won't affect you. In many cases, you can use automated tools to handle the upgrade for you. Follow this guide to get
+started.
+
+Upgrading for users
+--------------------
+
+For most projects, these are the main changes:
+
+* **PHP Configuration:** We now use PHP for configuration. YAML files are no longer supported. Behat will look for
+  ``behat.php`` or ``behat.dist.php`` in your current directory.
+* **PHP Attributes:** We've replaced PHPDoc annotations (like ``@Given`` or ``@BeforeScenario``) with native PHP
+  Attributes.
+* **Cleanup:** All previously deprecated features and code have been removed.
+* **New Parser Mode:** We now default to a newer parser compatibility mode
+  (:doc:`GHERKIN_32 </user_guide/gherkin/parser_mode>`).
+
+Step-by-step preparation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Before** you switch to Behat 4.0, we recommend taking these steps:
+
+1. **Update Behat 3:** Make sure you are using the latest version of Behat 3.x.
+2. **Convert Config:** If you use YAML, run ``vendor/bin/behat --convert-config`` to `convert it to PHP`_. Review the
+   results to make sure everything looks correct.
+3. **Check File Location:** If your config file is in a ``config/`` folder, move it to your project root or use the
+   ``--config`` flag when running Behat.
+4. **Update Extensions:** Make sure any extensions you use are referenced by their full class name (e.g.
+   ``Behat\MinkExtension\ServiceContainer\MinkExtension::class`` not ``Behat\MinkExtension```). The conversion tool
+   usually handles this.
+5. **Convert Annotations:** Use `Rector`_ with the ``->withAttributeSets(behat: true)`` rule to automatically change
+   `Behat annotations`_ into PHP Attributes.
+6. **Check Deprecations:** Run your tests with ``--fail-on-deprecations`` and fix any warnings that appear.
+7. **Test the New Parser:** Enable the :doc:`GHERKIN_32 parser mode </user_guide/gherkin/parser_mode>` and see if your
+   tests still run correctly. If you have issues, you can fix your feature files or use
+   ``GherkinCompatibilityMode::LEGACY`` in your config. This mode will be removed in the future.
+
+Ready to upgrade?
+~~~~~~~~~~~~~~~~~
+
+Once you've completed the steps above, update your ``composer.json`` to start using Behat 4.0!
+
+.. caution::
+   While we are in the alpha phase, we recommend using:
+   ``{"require": {"behat/behat": "4.0.0-alpha1@alpha"}}``.
+
+.. note::
+   Don't forget to update your third-party extensions to versions that support Behat 4.0. If you find one that hasn't
+   been updated yet, consider helping out by submitting a Pull Request! The community's help makes the transition faster
+   for everyone.
+
+
+Upgrading for extension authors
+-------------------------------
+
+It's possible to support both Behat 3.x and 4.x at the same time (for example, by using
+``{"require": {"behat/behat": "^3.x || ^4.x"}}``).
+
+If your project uses Behat to test itself, first follow the "Upgrading for users" steps above.
+
+Here are the key changes for all extension authors:
+
+* **Strict Types:** All interfaces and classes now use strict types for parameters, properties, and return values. As a
+  minimum, you will need to add return types to any methods that implement Behat interfaces or extend Behat classes.
+  `Rector`_ can automate this for you with the ``AddReturnTypeBasedOnParentClassMethodRector`` (included in the
+  ``typeDeclarations`` set).
+* **Public API:** We are now stricter about what is considered public API. This helps us maintain a solid
+  :doc:`backwards compatibility promise </releases/backwards-compatibility>`. If your extension needs to use code that
+  isn't marked public yet, please let us know.
+* **Full Class Names:** Users can no longer use "short names" for extensions (like ``Behat\MinkExtension``). They must
+  now use the fully-qualified class name of your ``Extension`` class. Please update your documentation to reflect this.
+* **Deprecations:** If your extension needs to report deprecations, we recommend using
+  ``Behat\Testwork\Deprecation\DeprecationCollector::trigger()`` (available since 3.30.0) instead of ``trigger_error``.
+  This ensures they are correctly handled by Behat's deprecation flags regardless of the user's runtime environment.
+* **Event Changes:** The ``ScenarioLikeTested`` base event class has been removed. ``ScenarioTested`` and
+  ``BackgroundTested`` are now separate. This may affect you if you maintain a formatter extension.
+
+There are several other changes that might affect a minority of extension authors. See the full
+`CHANGELOG`_ for details.
+
+Planned changes before the final 4.0.0 release
+----------------------------------------------
+
+We plan to make two more significant changes before the final 4.0.0 release:
+
+* **Parameter Matching:** We are reviewing how steps behave when the number of function parameters doesn't match the
+  step definition. This will likely trigger a deprecation or a failure. You can follow the progress in `#1691`_.
+* **PHPUnit Assertions:** Support for rendering PHPUnit assertion failures will move to a standalone extension. While
+  tests will still pass or fail, the output will be less detailed without the extension. We no longer recommend using
+  PHPUnit for assertions within Behat steps, as the PHPUnit project has confirmed this is not supported. See
+  `#1746`_ for details.
+
+We may make additional changes based on feedback from the community as more people begin to upgrade.
+
+.. _`convert it to PHP`: https://docs.behat.org/en/v3.x/user_guide/configuration/yaml_configuration.html#converting-your-configuration
+.. _`Rector`: https://getrector.com/documentation
+.. _`Behat annotations`: https://docs.behat.org/en/v3.x/user_guide/annotations.html#existing-code
+.. _`AddReturnTypeBasedOnParentClassMethodRector`: https://getrector.com/rule-detail/add-return-type-declaration-based-on-parent-class-method-rector
+.. _`CHANGELOG`: https://github.com/Behat/Behat/blob/4.x/CHANGELOG.md
+.. _`#1691`: https://github.com/Behat/Behat/issues/1691
+.. _`#1746`: https://github.com/Behat/Behat/issues/1746