Skip to content

Commit d085439

Browse files
committed
added a new page on experimental features
1 parent 4f7b7ea commit d085439

File tree

4 files changed

+31
-5
lines changed

4 files changed

+31
-5
lines changed

contributing/code/bc.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,9 @@ follow to ensure smooth upgrades for our users.
3434

3535
.. warning::
3636

37-
Code marked with the ``@experimental`` or the ``@internal`` tags is
38-
excluded from our Backward Compatibility promise.
37+
:doc:`Experimental Features </contributing/code/experimental>` and code
38+
marked with the ``@internal`` tags are excluded from our Backward
39+
Compatibility promise.
3940

4041
Also note that backward compatibility breaks are tolerated if they are
4142
required to fix a security issue.

contributing/code/experimental.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Experimental Features
2+
=====================
3+
4+
All Symfony features benefits from our :doc:`Backward Compatibility Promise
5+
</contributing/code/bc>` to give developers the confidence to upgrade to new
6+
versions safely and more often.
7+
8+
But sometimes, a new feature is controversial. Or finding a good API is not
9+
easy. In such cases, we want to be able to gather feedback from real-world
10+
usage, adapt the API, or remove it altogether. Doing so is not possible with a
11+
no BC-break approach.
12+
13+
To avoid being bound to our backward compatibility promise, such features can
14+
be marked as **experimental**; classes and methods parts of an experimental
15+
feature must be marked with the ``@experimental`` tag.
16+
17+
A feature can be marked as being experimental for only one minor version, and
18+
can never be introduced in an :ref:`LTS version <releases-lts>`. The core team
19+
can decide to extend the experimental period for another minor version on a
20+
case by case basis.
21+
22+
To ease upgrading projects using experimental features, the changelog must
23+
explain backward incompatible changes and explain how to upgrade code.

contributing/code/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Contributing Code
1111
security
1212
tests
1313
bc
14+
experimental
1415
standards
1516
conventions
1617
git

contributing/community/releases.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -150,9 +150,10 @@ of Symfony to the next one.
150150
Whenever keeping backward compatibility is not possible, the feature, the
151151
enhancement or the bug fix will be scheduled for the next major version.
152152

153-
However, features marked with the ``@experimental`` tag are **not** part of the
154-
backward compatibility promise and their APIs can change from one minor version
155-
to the next. The changelog must explain the changes and how to upgrade.
153+
However, :doc:`Experimental Features </contributing/code/experimental>` are
154+
**not** part of the backward compatibility promise and their APIs can change
155+
from one minor version to the next. The changelog must explain the changes and
156+
how to upgrade.
156157

157158
Deprecations
158159
------------

0 commit comments

Comments
 (0)