[DOCS] Add an API and deprecation policy

This is exactly the same change as in our sister project,
PHP-CSS-Parser:

MyIntervals/PHP-CSS-Parser#720

.gitattributes

@@ -6,6 +6,7 @@
 /CODE_OF_CONDUCT.md export-ignore
 /CONTRIBUTING.md export-ignore
 /config/ export-ignore
+/docs/ export-ignore
 /phpstan-baseline.neon export-ignore
 /phpstan.neon export-ignore
 /phpunit.xml export-ignore

CHANGELOG.md

@@ -3,6 +3,9 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+Please also have a look at our
+[API and deprecation policy](docs/API-and-deprecation-policy.md).
+
 ## x.y.z
 
 ### Added
@@ -18,6 +21,10 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Fixed
 
+### Documentation
+
+- Add an API and deprecation policy (#724)
+
 ## 7.2.0: Add support for Symfony 7
 
 ### Added

README.md

@@ -420,6 +420,11 @@ They will, however, be preserved and copied to a `<style>` element in the HTML:
   self-closing tags will lose their slash. To keep your HTML valid, it is
   recommended to use HTML5 instead of one of the XHTML variants.
 
+## API and deprecation policy
+
+Please have a look at our
+[API and deprecation policy](docs/API-and-deprecation-policy.md).
+
 ## Contributing
 
 Contributions in the form of bug reports, feature requests, or pull requests are

docs/API-and-deprecation-policy.md

@@ -0,0 +1,52 @@
+# API and Deprecation Policy
+
+## API Policy
+
+The code in this library is intended to be called by other projects. It is not
+intended to be extended. If you want to extend any classes, you're on your own,
+and your code might break with any new release of this library.
+
+Any classes, methods and properties that are `public` and not marked as
+`@internal` are considered to be part of the API. Those methods will continue
+working in a compatible way over minor and bug-fix releases according
+to [Semantic Versioning](https://semver.org/), though we might change the native
+type declarations in a way that could break subclasses.
+
+Any classes, methods and properties that are `protected` or `private` are _not_
+considered part of the API. Please do not rely on them. If you do, you're on
+your own.
+
+Any code that is marked as `@internal` is subject to change or removal without
+notice. Please do not call it. There be dragons.
+
+If a class is marked as `@internal`, all properties and methods of this class
+are by definition considered to be internal as well.
+
+When we change some code from public to `@internal` in a release, the first
+release that might change that code in a breaking way will be the next major
+release after that. This will allow you to change your code accordingly. We'll
+also add since which version the code is internal.
+
+For example, we might mark some code as `@internal` in version 8.7.0. The first
+version that possibly changes this code in a breaking way will then be version
+9.0.0.
+
+Before you upgrade your code to the next major version of this library, please
+update to the latest release of the previous major version and make sure that
+your code does not reference any code that is marked as `@internal`.
+
+## Deprecation Policy
+
+Code that we plan to remove is marked as `@deprecated`. In the corresponding
+annotation, we also note in which release the code will be removed.
+
+When we mark some code as `@deprecated` in a release, we'll usually remove it in
+the next major release. We'll also add since which version the code is
+deprecated.
+
+For example, when we mark some code as `@deprecated` in version 8.7.0, we'll
+remove it in version 9.0.0 (or sometimes a later major release).
+
+Before you upgrade your code to the next major version of this library, please
+update to the latest release of the previous major version and make sure that
+your code does not reference any code that is marked as `@deprecated`.