File tree Expand file tree Collapse file tree 4 files changed +31
-5
lines changed Expand file tree Collapse file tree 4 files changed +31
-5
lines changed Original file line number Diff line number Diff line change @@ -34,8 +34,9 @@ follow to ensure smooth upgrades for our users.
34
34
35
35
.. warning ::
36
36
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.
39
40
40
41
Also note that backward compatibility breaks are tolerated if they are
41
42
required to fix a security issue.
Original file line number Diff line number Diff line change
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.
Original file line number Diff line number Diff line change @@ -11,6 +11,7 @@ Contributing Code
11
11
security
12
12
tests
13
13
bc
14
+ experimental
14
15
standards
15
16
conventions
16
17
git
Original file line number Diff line number Diff line change @@ -150,9 +150,10 @@ of Symfony to the next one.
150
150
Whenever keeping backward compatibility is not possible, the feature, the
151
151
enhancement or the bug fix will be scheduled for the next major version.
152
152
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.
156
157
157
158
Deprecations
158
159
------------
You can’t perform that action at this time.
0 commit comments