|
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 ofSymfony (such as |
23 | | -2.5, 2.6 and so on). |
| 40 | +you to ensure smooth upgrades to all future minor releases ofyour 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 |
|