diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index f11ab49ba08..71d19989d2d 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -32,6 +32,15 @@ The second section, "Working on Symfony Code", is targeted at Symfony contributors. This section lists detailed rules that every contributor needs to follow to ensure smooth upgrades for our users. +.. warning:: + + :doc:`Experimental Features ` and code + marked with the ``@internal`` tags are excluded from our Backward + Compatibility promise. + + Also note that backward compatibility breaks are tolerated if they are + required to fix a security issue. + Using Symfony Code ------------------ diff --git a/contributing/code/experimental.rst b/contributing/code/experimental.rst new file mode 100644 index 00000000000..49d969b47f2 --- /dev/null +++ b/contributing/code/experimental.rst @@ -0,0 +1,23 @@ +Experimental Features +===================== + +All Symfony features benefit from our :doc:`Backward Compatibility Promise +` to give developers the confidence to upgrade to new +versions safely and more often. + +But sometimes, a new feature is controversial. Or finding a good API is not +easy. In such cases, we prefer to gather feedback from real-world usage, adapt +the API, or remove it altogether. Doing so is not possible with a no BC-break +approach. + +To avoid being bound to our backward compatibility promise, such features can +be marked as **experimental** and their classes and methods must be marked with +the ``@experimental`` tag. + +A feature can be marked as being experimental for only one minor version, and +can never be introduced in a :ref:`LTS version `. The core team +can decide to extend the experimental period for another minor version on a +case by case basis. + +To ease upgrading projects using experimental features, the changelog must +explain backward incompatible changes and explain how to upgrade code. diff --git a/contributing/code/index.rst b/contributing/code/index.rst index 0fc8241ad46..18a1e22dc05 100644 --- a/contributing/code/index.rst +++ b/contributing/code/index.rst @@ -11,6 +11,7 @@ Contributing Code security tests bc + experimental standards conventions git diff --git a/contributing/community/releases.rst b/contributing/community/releases.rst index 8ecc57ff6af..95dba057c3e 100644 --- a/contributing/community/releases.rst +++ b/contributing/community/releases.rst @@ -150,6 +150,11 @@ of Symfony to the next one. Whenever keeping backward compatibility is not possible, the feature, the enhancement or the bug fix will be scheduled for the next major version. +However, :doc:`Experimental Features ` are +**not** part of the backward compatibility promise and their APIs can change +from one minor version to the next. The changelog must explain the changes and +how to upgrade. + Deprecations ------------