Soft-finalize classes that might need to be changed in the future (#41)

* Soft-finalize classes that might need to be changed in the future

* Leave a note in the UPGRADING document

* @internal-ize listener classes

UPGRADING.md

@@ -0,0 +1,11 @@
+# Upgrade notes for FriendsOfBehat/MinkExtension
+
+This document summarizes the changes relevant for users when upgrading to new versions.
+
+# Upgrade to 2.8
+
+## Soft `@final` and `@internal` declarations added
+
+The classes `FailureShowListener`, `SessionsListener` and `MinkExtension` have been marked as `@final`. They will become `final` classes in the next major release and you will no longer be able to use them by inheritance (https://github.com/FriendsOfBehat/MinkExtension/pull/41).
+
+Additionally, the two listener classes have been marked as `@internal`. Starting with the next major version, their API may change at any time without further notice.

src/Behat/MinkExtension/Listener/FailureShowListener.php

@@ -22,6 +22,9 @@ use Behat\Mink\Exception\Exception as MinkException;
  * Listens to failed Behat steps and shows last response in a browser.
  *
  * @author Konstantin Kudryashov <ever.zet@gmail.com>
+ *
+ * @final since 2.8.0
+ * @internal since 2.8.0
  */
 class FailureShowListener implements EventSubscriberInterface
 {

src/Behat/MinkExtension/Listener/SessionsListener.php

@@ -25,6 +25,9 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  * Listens Behat events and configures/stops Mink sessions.
  *
  * @author Konstantin Kudryashov <ever.zet@gmail.com>
+ *
+ * @final since 2.8.0
+ * @internal since 2.8.0
  */
 class SessionsListener implements EventSubscriberInterface
 {

src/Behat/MinkExtension/ServiceContainer/MinkExtension.php

@@ -38,6 +38,8 @@ use Symfony\Component\DependencyInjection\Reference;
  *
  * @author Konstantin Kudryashov <ever.zet@gmail.com>
  * @author Christophe Coevoet <stof@notk.org>
+ *
+ * @final since 2.8.0
  */
 class MinkExtension implements ExtensionInterface
 {