From 4f7b7ea5c65e7cbc62b1c36a161263592ac3d3be Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Thu, 26 Jan 2017 11:54:35 -0800 Subject: [PATCH 1/2] added a note about experimental features --- contributing/code/bc.rst | 8 ++++++++ contributing/community/releases.rst | 4 ++++ 2 files changed, 12 insertions(+) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index f11ab49ba08..12156f591d0 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -32,6 +32,14 @@ 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:: + + Code marked with the ``@experimental`` or the ``@internal`` tags is + 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/community/releases.rst b/contributing/community/releases.rst index 8ecc57ff6af..c422a2abbdd 100644 --- a/contributing/community/releases.rst +++ b/contributing/community/releases.rst @@ -150,6 +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. + Deprecations ------------ From 42c3ec99dddae386cd2b43ab920a70d3b80f9939 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Sun, 12 Feb 2017 17:10:55 +0100 Subject: [PATCH 2/2] added a new page on experimental features --- contributing/code/bc.rst | 5 +++-- contributing/code/experimental.rst | 23 +++++++++++++++++++++++ contributing/code/index.rst | 1 + contributing/community/releases.rst | 7 ++++--- 4 files changed, 31 insertions(+), 5 deletions(-) create mode 100644 contributing/code/experimental.rst diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 12156f591d0..71d19989d2d 100644 --- a/contributing/code/bc.rst +++ b/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 ` 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. 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 c422a2abbdd..95dba057c3e 100644 --- a/contributing/community/releases.rst +++ b/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 ` 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 ------------