Closes #3236

ChangeLog-8.0.md

@@ -7,6 +7,7 @@ All notable changes of the PHPUnit 8.0 release series are documented in this fil
 ### Changed
 
 * Implemented [#3133](https://github.com/sebastianbergmann/phpunit/issues/3133): Enable dependency resolution by default
+* Implemented [#3236](https://github.com/sebastianbergmann/phpunit/issues/3236): Define which parts of PHPUnit are covered by the backward compatibility promise
 * Implemented [#3244](https://github.com/sebastianbergmann/phpunit/issues/3244): Enable result cache by default
 * Implemented [#3288](https://github.com/sebastianbergmann/phpunit/issues/3288): The `void_return` fixer of php-cs-fixer is now in effect
 * Implemented [#3332](https://github.com/sebastianbergmann/phpunit/issues/3332): Deprecate annotation(s) for expecting exceptions

src/Exception.php

@@ -10,7 +10,7 @@
 namespace PHPUnit;
 
 /**
- * Marker interface for PHPUnit exceptions.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface Exception
 {

src/Framework/AssertionFailedError.php

@@ -10,7 +10,7 @@
 namespace PHPUnit\Framework;
 
 /**
- * Thrown when an assertion failed.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 class AssertionFailedError extends Exception implements SelfDescribing
 {

src/Framework/CodeCoverageException.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 class CodeCoverageException extends Exception
 {
 }

src/Framework/CoveredCodeNotExecutedException.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class CoveredCodeNotExecutedException extends RiskyTestError
 {
 }

src/Framework/DataProviderTestSuite.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class DataProviderTestSuite extends TestSuite
 {
     /**

src/Framework/Error/Deprecated.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework\Error;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class Deprecated extends Error
 {
     public static $enabled = true;

src/Framework/Error/Error.php

@@ -12,7 +12,7 @@
 use PHPUnit\Framework\Exception;
 
 /**
- * Wrapper for PHP errors.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 class Error extends Exception
 {

src/Framework/Error/Notice.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework\Error;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class Notice extends Error
 {
     public static $enabled = true;

src/Framework/Error/Warning.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework\Error;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class Warning extends Error
 {
     public static $enabled = true;

src/Framework/Exception.php

@@ -30,6 +30,7 @@
  * the parent would break the intended encapsulation of process isolation.
  *
  * @see http://fabien.potencier.org/article/9/php-serialization-stack-traces-and-exceptions
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 class Exception extends \RuntimeException implements \PHPUnit\Exception
 {

src/Framework/ExceptionWrapper.php

@@ -20,6 +20,8 @@
  *
  * Unlike PHPUnit\Framework_\Exception, the complete stack of previous Exceptions
  * is processed.
+ *
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class ExceptionWrapper extends Exception
 {

src/Framework/ExpectationFailedException.php

@@ -17,6 +17,8 @@
  * The exception contains the error message and optionally a
  * SebastianBergmann\Comparator\ComparisonFailure which is used to
  * generate diff output of the failed expectations.
+ *
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class ExpectationFailedException extends AssertionFailedError
 {

src/Framework/IncompleteTest.php

@@ -10,8 +10,7 @@
 namespace PHPUnit\Framework;
 
 /**
- * A marker interface for marking any exception/error as result of an unit
- * test as incomplete implementation or currently not implemented.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface IncompleteTest
 {

src/Framework/IncompleteTestCase.php

@@ -10,7 +10,7 @@
 namespace PHPUnit\Framework;
 
 /**
- * An incomplete test case
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class IncompleteTestCase extends TestCase
 {

src/Framework/IncompleteTestError.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class IncompleteTestError extends AssertionFailedError implements IncompleteTest
 {
 }

src/Framework/InvalidCoversTargetException.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class InvalidCoversTargetException extends CodeCoverageException
 {
 }

src/Framework/InvalidDataProviderException.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class InvalidDataProviderException extends Exception
 {
 }

src/Framework/MissingCoversAnnotationException.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class MissingCoversAnnotationException extends RiskyTestError
 {
 }

src/Framework/MockObject/Builder/Identity.php

@@ -10,12 +10,7 @@
 namespace PHPUnit\Framework\MockObject\Builder;
 
 /**
- * Builder interface for unique identifiers.
- *
- * Defines the interface for recording unique identifiers. The identifiers
- * can be used to define the invocation order of expectations. The expectation
- * is recorded using id() and then defined in order using
- * PHPUnit\Framework\MockObject\Builder\Match::after().
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface Identity
 {

src/Framework/MockObject/Builder/InvocationMocker.php

@@ -17,12 +17,7 @@
 use PHPUnit\Framework\MockObject\Stub\MatcherCollection;
 
 /**
- * Builder for mocked or stubbed invocations.
- *
- * Provides methods for building expectations without having to resort to
- * instantiating the various matchers manually. These methods also form a
- * more natural way of reading the expectation. This class should be together
- * with the test case PHPUnit\Framework\MockObject\TestCase.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class InvocationMocker implements MethodNameMatch
 {

src/Framework/MockObject/Builder/Match.php

@@ -10,7 +10,7 @@
 namespace PHPUnit\Framework\MockObject\Builder;
 
 /**
- * Builder interface for invocation order matches.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface Match extends Stub
 {

src/Framework/MockObject/Builder/MethodNameMatch.php

@@ -10,7 +10,7 @@
 namespace PHPUnit\Framework\MockObject\Builder;
 
 /**
- * Builder interface for matcher of method names.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface MethodNameMatch extends ParametersMatch
 {

src/Framework/MockObject/Builder/NamespaceMatch.php

@@ -10,9 +10,7 @@
 namespace PHPUnit\Framework\MockObject\Builder;
 
 /**
- * Interface for builders which can register builders with a given identification.
- *
- * This interface relates to Identity.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface NamespaceMatch
 {

src/Framework/MockObject/Builder/ParametersMatch.php

@@ -12,7 +12,7 @@
 use PHPUnit\Framework\MockObject\Matcher\AnyParameters;
 
 /**
- * Builder interface for parameter matchers.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface ParametersMatch extends Match
 {

src/Framework/MockObject/Builder/Stub.php

@@ -12,7 +12,7 @@
 use PHPUnit\Framework\MockObject\Stub as BaseStub;
 
 /**
- * Builder interface for stubs which are actions replacing an invocation.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface Stub extends Identity
 {

src/Framework/MockObject/Exception/BadMethodCallException.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework\MockObject;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class BadMethodCallException extends \BadMethodCallException implements Exception
 {
 }

src/Framework/MockObject/Exception/Exception.php

@@ -10,7 +10,7 @@
 namespace PHPUnit\Framework\MockObject;
 
 /**
- * Interface for exceptions used by PHPUnit_MockObject.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface Exception
 {

src/Framework/MockObject/Exception/RuntimeException.php

@@ -9,6 +9,9 @@
  */
 namespace PHPUnit\Framework\MockObject;
 
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
 final class RuntimeException extends \RuntimeException implements Exception
 {
 }

src/Framework/MockObject/Generator.php

@@ -22,7 +22,7 @@
 use Traversable;
 
 /**
- * Mock Object Code Generator
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class Generator
 {

src/Framework/MockObject/Invocation/Invocation.php

@@ -10,7 +10,7 @@
 namespace PHPUnit\Framework\MockObject;
 
 /**
- * Interface for invocations.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface Invocation
 {

src/Framework/MockObject/Invocation/ObjectInvocation.php

@@ -10,7 +10,7 @@
 namespace PHPUnit\Framework\MockObject\Invocation;
 
 /**
- * Represents a non-static invocation.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class ObjectInvocation extends StaticInvocation
 {

src/Framework/MockObject/Invocation/StaticInvocation.php

@@ -16,7 +16,7 @@
 use SebastianBergmann\Exporter\Exporter;
 
 /**
- * Represents a static invocation.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 class StaticInvocation implements Invocation, SelfDescribing
 {

src/Framework/MockObject/InvocationMocker.php

@@ -19,11 +19,7 @@
 use PHPUnit\Framework\MockObject\Stub\MatcherCollection;
 
 /**
- * Mocker for invocations which are sent from
- * MockObject objects.
- *
- * Keeps track of all expectations and stubs as well as registering
- * identifications for builders.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class InvocationMocker implements MatcherCollection, Invokable, NamespaceMatch
 {

src/Framework/MockObject/Invokable.php

@@ -10,10 +10,7 @@
 namespace PHPUnit\Framework\MockObject;
 
 /**
- * Interface for classes which can be invoked.
- *
- * The invocation will be taken from a mock object and passed to an object
- * of this class.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 interface Invokable extends Verifiable
 {

src/Framework/MockObject/Matcher.php

@@ -19,13 +19,7 @@
 use PHPUnit\Framework\TestFailure;
 
 /**
- * Main matcher which defines a full expectation using method, parameter and
- * invocation matchers.
- * This matcher encapsulates all the other matchers and allows the builder to
- * set the specific matchers when the appropriate methods are called (once(),
- * where() etc.).
- *
- * All properties are public so that they can easily be accessed by the builder.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class Matcher implements MatcherInvocation
 {

src/Framework/MockObject/Matcher/AnyInvokedCount.php

@@ -10,8 +10,7 @@
 namespace PHPUnit\Framework\MockObject\Matcher;
 
 /**
- * Invocation matcher which checks if a method has been invoked zero or more
- * times. This matcher will always match.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class AnyInvokedCount extends InvokedRecorder
 {

src/Framework/MockObject/Matcher/AnyParameters.php

@@ -12,7 +12,7 @@
 use PHPUnit\Framework\MockObject\Invocation as BaseInvocation;
 
 /**
- * Invocation matcher which allows any parameters to a method.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class AnyParameters extends StatelessInvocation
 {

src/Framework/MockObject/Matcher/ConsecutiveParameters.php

@@ -15,14 +15,7 @@
 use PHPUnit\Framework\MockObject\Invocation as BaseInvocation;
 
 /**
- * Invocation matcher which looks for sets of specific parameters in the invocations.
- *
- * Checks the parameters of the incoming invocations, the parameter list is
- * checked against the defined constraints in $parameters. If the constraint
- * is met it will return true in matches().
- *
- * It takes a list of match groups and and increases a call index after each invocation.
- * So the first invocation uses the first group of constraints, the second the next and so on.
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
  */
 final class ConsecutiveParameters extends StatelessInvocation
 {