added a note about experimental features #7419
Conversation
|
http://symfony.com/blog/experimental-features for more information about this change. |
contributing/community/releases.rst
Outdated
| @@ -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 | |||
There was a problem hiding this comment.
"backwards" misses its 's'
There was a problem hiding this comment.
Misses on purpose - there's nothing like "backwards compatibility".
There was a problem hiding this comment.
@Wirone : if that's true the occurences of "backwards compatibility" in this PR should be removed.
There was a problem hiding this comment.
see #7462 to fix existing occurrences.
contributing/code/bc.rst
Outdated
| Code marked with the ``@experimental`` or the ``@internal`` tags are | ||
| excluded from our Backwards Compatibility promise. | ||
|
|
||
| Also note that backward compatibility breaks are tolerated if they help fix |
There was a problem hiding this comment.
The "s" misses here too (I think it is actually correct, but it seems to be written with an "s" in the bc promise doc)
There was a problem hiding this comment.
Your reference seems to state backward without the trailing s is the most appropriate as an adjective:
If you’re using British English, it’s typically backwards as an adverb and backward as an adjective, so you have two things to remember.
So maybe the BC promise doc should be updated instead 😄
There was a problem hiding this comment.
So maybe the BC promise doc should be updated instead 😄
So should the first sentence of this PR then :P … maybe pick one and stick with it?
contributing/code/bc.rst
Outdated
| @@ -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 are | |||
|
Why not place experimental features in a separate repository? Once they're finalized, they can then be merged into the main repository with commit history intact. |
|
@kherge Because most people would't use them. Experimental features need feedback, and having them in core helps a lot. |
There was a problem hiding this comment.
👍
There were somme comments about "backward compat..." vs "backwardS compat..." Let's ask our native English friend @weaverryan about this. Thanks!
There was a problem hiding this comment.
- Should we add a note about
@finalalso? - What about experimental feats + LTS? They look contradictory to me. Should we have a written policy saying we don't add experimental feats to LTS?
- How long can a feat be marked as experimental? Only for one release to me - the next one should either drop, release as stable, or at least update the
@experimentaltag to explicitly mention the extended laboratory period?
In this spirit, I used@experimental in version 3.3annotations in [DI] Add getter injection symfony#20973.
contributing/code/bc.rst
Outdated
| excluded from our Backwards Compatibility promise. | ||
|
|
||
| Also note that backward compatibility breaks are tolerated if they help fix | ||
| a security issue. |
There was a problem hiding this comment.
if they help fix a security issue => if they are required to fix a security issue?
contributing/community/releases.rst
Outdated
| @@ -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. | |||
There was a problem hiding this comment.
s/must/should/? It's not always worth the burden (eg we didn't follow that "must" for LDAP, and it was fine?)
There was a problem hiding this comment.
57A0That's a must. We didn't do that for LDAP and people now are confused.
ac6ba28 to
4f7b7ea
Compare
|
I've created a new document on experimental features to add some more details. |
contributing/code/experimental.rst
Outdated
| Experimental Features | ||
| ===================== | ||
|
|
||
| All Symfony features benefits from our :doc:`Backward Compatibility Promise |
contributing/code/experimental.rst
Outdated
| versions safely and more often. | ||
|
|
||
| But sometimes, a new feature is controversial. Or finding a good API is not | ||
| easy. In such cases, we want to be able to gather feedback from real-world |
There was a problem hiding this comment.
we want to be able to gather feedback -> we prefer to gather feedback ?
contributing/code/experimental.rst
Outdated
|
|
||
| To avoid being bound to our backward compatibility promise, such features can | ||
| be marked as **experimental**; classes and methods parts of an experimental | ||
| feature must be marked with the ``@experimental`` tag. |
There was a problem hiding this comment.
...; classes and methods parts of an experimental feature must be marked ... -> ... and their classes and methods must be marked ... ?
contributing/code/experimental.rst
Outdated
| feature 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 an :ref:`LTS version <releases-lts>`. The core team |
d085439 to
42c3ec9
Compare
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
I think
mastermakes sense here as no experimental features can be added anymore in earlier versions.