added a new page on experimental features

Author: fabpot

contributing/code/bc.rst

@@ -34,8 +34,9 @@ follow to ensure smooth upgrades for our users.
 
 .. warning::
 
-    Code marked with the ``@experimental`` or the ``@internal`` tags is
-    excluded from our Backward Compatibility promise.
+    :doc:`Experimental Features </contributing/code/experimental>` 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.

contributing/code/experimental.rst

@@ -0,0 +1,23 @@
+Experimental Features
+=====================
+
+All Symfony features benefit from our :doc:`Backward Compatibility Promise
+</contributing/code/bc>` 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 <releases-lts>`. 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.

contributing/code/index.rst

@@ -11,6 +11,7 @@ Contributing Code
     security
     tests
     bc
+    experimental
     standards
     conventions
     git

contributing/community/releases.rst

@@ -150,9 +150,10 @@ 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, features marked with the ``@experimental`` tag 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.
+However, :doc:`Experimental Features </contributing/code/experimental>` 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
 ------------