feature #7419 added a note about experimental features (fabpot)

weaverryan · weaverryan · commit 9b9f5a1b2677 · 2017-02-16T19:37:22.000-05:00
This PR was merged into the master branch. Discussion ---------- added a note about experimental features I think `master` makes sense here as no experimental features can be added anymore in earlier versions. Commits ------- 42c3ec9 added a new page on experimental features 4f7b7ea added a note about experimental features
diff --git 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 </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.
+
 Using Symfony Code
 ------------------
 
diff --git a/contributing/code/experimental.rst b/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.
diff --git 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
@@ -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 </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
 ------------
 
