|
1 | 1 | Our Backwards Compatibility Promise
|
2 | 2 | ===================================
|
3 | 3 |
|
4 |
| -If you are using Symfony, we promise you backwards compatibility (BC) for all |
5 |
| -minor releases (2.5, 2.6, etc.). Ensuring smooth upgrades of your projects is our |
6 |
| -first priority. However, backwards compatibility comes in many different flavors. |
| 4 | +Ensuring smooth upgrades of your projects is our first priority. That's why |
| 5 | +we promise you backwards compatibility (BC) for all minor Symfony releases. |
| 6 | + |
| 7 | +You probably recognize this strategy as `Semantic Versioning`_. In short, |
| 8 | +Semantic Versioning means that only major releases (such as 2.0, 3.0 etc.) are |
| 9 | +allowed to break backwards compatibility. Minor releases (such as 2.5, 2.6 etc.) |
| 10 | +may introduce new features, but must do so without breaking the existing API of |
| 11 | +that release branch (2.x in the previous example). |
7 | 12 |
|
8 | 13 | .. caution::
|
9 | 14 |
|
10 | 15 | This promise was introduced with Symfony 2.3 and does not apply to previous
|
11 | 16 | versions of Symfony.
|
12 | 17 |
|
13 |
| -This page has two different target audiences: If you are using Symfony, it will |
14 |
| -tell you how to make sure that you will be able to upgrade smoothly to all |
15 |
| -future 2.x versions. If you are contributing to Symfony, this page will tell you |
16 |
| -the rules that you need to follow to ensure smooth upgrades for our users. |
| 18 | +However, backwards compatibility comes in many different flavors. In fact, almost |
| 19 | +every change that we make to the framework can potentially break an application. |
| 20 | +For example, if we add a new method to a class, this will break an application |
| 21 | +which extended this class and added the same method, but with a different |
| 22 | +method signature. |
| 23 | + |
| 24 | +Also, not every BC break has the same impact on application code. While some BC |
| 25 | +breaks require you to make significant changes to your classes or your |
| 26 | +architecture, others are fixed as easily as changing the name of a method. |
| 27 | + |
| 28 | +That's why we created this page for you. The section "Using Symfony Code" will |
| 29 | +tell you how you can ensure that your application won't break completely when |
| 30 | +upgrading to a newer version of the same major release branch. |
| 31 | + |
| 32 | +The second section, "Working on Symfony Code", is targeted at Symfony |
| 33 | +contributors. This section lists detailed rules that every contributor needs to |
| 34 | +follow to ensure smooth upgrades for our users. |
17 | 35 |
|
18 | 36 | Using Symfony Code
|
19 | 37 | ------------------
|
20 | 38 |
|
21 | 39 | If you are using Symfony in your projects, the following guidelines will help
|
22 |
| -you to ensure smooth upgrades to all future minor releases of Symfony (such as |
23 |
| -2.5, 2.6 and so on). |
| 40 | +you to ensure smooth upgrades to all future minor releases of your Symfony |
| 41 | +version. |
24 | 42 |
|
25 | 43 | Using Our Interfaces
|
26 | 44 | ~~~~~~~~~~~~~~~~~~~~
|
@@ -299,6 +317,7 @@ Change return type Yes [2]_ [5]_ No
|
299 | 317 | .. [7] A type hint may only be added if passing a value with a different type
|
300 | 318 | previously generated a fatal error.
|
301 | 319 |
|
| 320 | +.. _Semantic Versioning: http://semver.org/ |
302 | 321 | .. _scalar type: http://php.net/manual/en/function.is-scalar.php
|
303 | 322 | .. _boolean values: http://php.net/manual/en/function.boolval.php
|
304 | 323 | .. _string values: http://www.php.net/manual/en/function.strval.php
|
|
0 commit comments