Skip to content

Commit 90c4de6

Browse files
committed
Mentioned Semantic Versioning in the introduction
1 parent 2320906 commit 90c4de6

File tree

1 file changed

+28
-9
lines changed

1 file changed

+28
-9
lines changed

contributing/code/bc.rst

+28-9
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,44 @@
11
Our Backwards Compatibility Promise
22
===================================
33

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).
712

813
.. caution::
914

1015
This promise was introduced with Symfony 2.3 and does not apply to previous
1116
versions of Symfony.
1217

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.
1735

1836
Using Symfony Code
1937
------------------
2038

2139
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.
2442

2543
Using Our Interfaces
2644
~~~~~~~~~~~~~~~~~~~~
@@ -299,6 +317,7 @@ Change return type Yes [2]_ [5]_ No
299317
.. [7] A type hint may only be added if passing a value with a different type
300318
previously generated a fatal error.
301319
320+
.. _Semantic Versioning: http://semver.org/
302321
.. _scalar type: http://php.net/manual/en/function.is-scalar.php
303322
.. _boolean values: http://php.net/manual/en/function.boolval.php
304323
.. _string values: http://www.php.net/manual/en/function.strval.php

0 commit comments

Comments
 (0)