Added details about backwards compatibility

Thanks, Symfony team!

docs/internals/README.md

@@ -33,6 +33,7 @@ Versioning and Release
 
 - [Project Organization](project-organization.md)
 - [Yii Versioning](versions.md)
+- [Backwards Compatibility](bc.md)
 - [Releasing a new version](release.md)
 
 Misc

docs/internals/bc.md

@@ -0,0 +1,152 @@
+# Backwards Compatibility
+
+We're strictly not breaking backwards compatibility in patch releases such as `2.x.y.Z` and trying to avoid had to fix
+backwards incompatible changes in minor releases such as `2.x.Y`.
+
+Check [Yii Versioning](versions.md) to learn about version numbering. 
+
+## Usage
+
+### Interfaces
+
+Use case | BC?
+---------|----
+Type hint with the interface | Yes
+Call the interface method | Yes
+**Implement the interface and...** |
+Implement method | Yes
+Add argument to method implemented | Yes
+Add default value to an argument | Yes
+
+### Classes
+
+Use case | BC?
+---------|----
+Type hint with the class | Yes
+Create a new instance | Yes
+Extend the class | Yes
+Access a public property | Yes
+Call a public method | Yes
+**Extend the class and...** |
+Access a protected property	| Yes
+Call a protected method	| Yes
+Override a public property | Yes
+Override a protected property | Yes
+Override a public method | Yes
+Override a protected method | Yes
+Add a new property | No
+Add a new method | No
+Add an argument to an overridden method	| Yes
+Add a default value to an argument | Yes
+Call a private method (via Reflection) | No
+Access a private property (via Reflection) | No
+
+
+## Development
+
+### Changing interfaces
+
+Type of change | BC?
+---------------|----
+Remove | No
+Change name or namespace | No
+Add parent interface | Yes if no new methods are added
+Remove parent interface | No
+**Interface methods** | 
+Add method | No
+Remove method | No
+Change name | No
+Move to parent interface | Yes
+Add argument without a default value | No
+Add argument with a default value | No
+Remove argument | Yes (only last ones)
+Add default value to an argument | No
+Remove default value of an argument | No
+Add type hint to an argument | No
+Remove type hint of an argument | No
+Change argument type | No
+Change return type | No
+**Constants** |	 
+Add constant | Yes
+Remove constant | No
+Change value of a constant | Yes except objects that are likely to be serialized. Mandatory to document in UPGRADE.md.
+
+### Classes
+
+Type of change | BC?
+---------------|----
+Remove | No
+Make final | No
+Make abstract | No
+Change name or namespace | No
+Change parent class | Yes but original parent class must remain an ancestor of the class.
+Add interface | Yes
+Remove interface | No
+**Public Properties** | 
+Add public property | Yes
+Remove public property | No
+Reduce visibility | No
+Move to parent class | Yes
+**Protected Properties** | 	 
+Add protected property | Yes
+Remove protected property | No
+Reduce visibility | No
+Move to parent class | Yes
+**Private Properties** | 
+Add private property | Yes
+Remove private property | Yes
+**Constructors** | 
+Remove constructor | No
+Reduce visibility of a public constructor | No
+Reduce visibility of a protected constructor | No
+Move to parent class | Yes
+**Public Methods** |
+Add public method | Yes
+Remove public method | No
+Change name | No
+Reduce visibility | No
+Move to parent class | Yes
+Add argument without a default value | No
+Add argument with a default value | No
+Remove arguments | Yes, only last ones
+Add default value to an argument | No
+Remove default value of an argument | No
+Add type hint to an argument | No
+Remove type hint of an argument | No
+Change argument type | No
+Change return type | No
+**Protected Methods** | 	 
+Add protected method | Yes
+Remove protected method | No
+Change name | No
+Reduce visibility | No
+Move to parent class | Yes
+Add argument without a default value | No
+Add argument with a default value | No
+Remove arguments | Yes, only last ones
+Add default value to an argument | No
+Remove default value of an argument | No
+Add type hint to an argument | No
+Remove type hint of an argument | No
+Change argument type | No
+Change return type | No
+**Private Methods** | 	 
+Add private method | Yes
+Remove private method | Yes
+Change name | Yes
+Add argument without a default value | Yes
+Add argument with a default value | Yes
+Remove argument | Yes
+Add default value to an argument | Yes
+Remove default value of an argument | Yes
+Add type hint to an argument | Yes
+Remove type hint of an argument | Yes
+Change argument type | Yes
+Change return type | Yes
+**Static Methods** | 
+Turn non static into static | No
+Turn static into non static | No
+**Constants** | 	 
+Add constant | Yes
+Remove constant | No
+Change value of a constant | Yes except objects that are likely to be serialized. Mandatory to document in UPGRADE.md.

docs/internals/versions.md

@@ -1,13 +1,12 @@
 Yii Versioning
 ==============
 
-This document summarizes the versioning policy of Yii. Our current versioning strategy can be
-described as [ferver](https://github.com/jonathanong/ferver), which we considered is more practical
-and reasonable than [Semantic Versioning](http://semver.org/) (See [#7408](https://github.com/yiisoft/yii2/issues/7408) for more references).
+This document summarizes the versioning policy of Yii. Our current versioning strategy is
+a variant of [Semantic Versioning](http://semver.org/).
 
-Within the core developer team, we have emphasized several times that it is important to keep 2.0.x releases 100% BC-compatible.
-But this is an ideal plan. The ferver article has given out a real world example that this is hard to achieve in practice,
-regardless you are using semver or not.
+Within the core developer team, we have emphasized several times that it is important to keep 2.0.x releases backwards
+compatible. But this is an ideal plan. In a real world this is hard to achieve. See [Backwards Compatibility](bc.md)
+document for detailed description of what BC is.
 
 In summary, our versioning policy for Yii 2 is as follows:
 
@@ -20,8 +19,8 @@ depending on external technology advancement (such as PHP upgraded from 5.0 to 5
 
 ### `2.X.0`: major releases
 
-BC-breaking releases, which contain major features and changes that may break BC. Upgrading from earlier versions may
-not be trivial, but a complete upgrade guide will be available.
+Backwards compatibility breaking releases, which contain major features and changes that may break BC. Upgrading from
+earlier versions may not be trivial, but a complete upgrade guide will be available.
 
 * Mainly contain new features and bug fixes
 * Contain minor features and bug fixes merged from patch releases.
@@ -33,14 +32,14 @@ not be trivial, but a complete upgrade guide will be available.
 
 ### `2.x.Y`: minor releases
 
-Patch releases, which should be 100% BC-compatible. Ideally, we hope they contain only changes that do not affect backwards compatibility
-however it is not always possible to keep 100% BC-compatible, so upgrade notes are recorded in `UPGRADE.md`.
-Practically, since 2.0.x is released more frequently, we are also adding minor features
+Minor releases, which are mostly BC-compatible. Ideally, we hope they contain only changes that do not affect backwards
+compatibility. However, it is not always possible to keep everything 100% BC-compatible, so upgrade notes are recorded
+in `UPGRADE.md`. Practically, since 2.0.x is released more frequently, we are also adding minor features
 to it so that users can enjoy them earlier.
 
-* Mainly contain bug fixes and minor feature enhancements
-* No major features or changes.
-* Should be 100% backward compatible to ensure worry-free upgrade. Only a few exceptions are allowed which are documented in `UPGRADE.md`.
+* Mainly contain bug fixes and enhancements
+* Should be mostly backwards compatible to ensure worry-free upgrade. Only a few exceptions are allowed which are documented
+  in `UPGRADE.md`.
 * Release cycle is around 1 to 2 months.
 * No pre-releases (alpha, beta, RC) needed.
 * Should be merged back to master branch constantly (at least once every week manually).
@@ -51,13 +50,13 @@ to it so that users can enjoy them earlier.
 
 Patch releases, which should be 100% BC-compatible, containing bug fixes only.
 No news announcement or project site update (unless it contains major/security issue fixes).
-The release process will be made mostly automatic.
+The release process is mostly automatic.
 
-* containing bug fixes only, no features included.
-* Must be 100% backward compatible to ensure worry-free upgrade. Only exception is security issues that may require breaking BC.
-* Release cycle is around 1 to 2 weeks.
-* No pre-releases (alpha, beta, RC) needed.
-* Should be merged back to master branch on release.
+* Containing bug fixes only, no features included
+* Must be 100% backward compatible to ensure worry-free upgrade. Only exception is security issues that may require breaking BC
+* Release cycle is around 1 to 2 weeks
+* No pre-releases (alpha, beta, RC) needed
+* Should be merged back to master branch on release
 
 
 ## Branching policy
@@ -77,10 +76,9 @@ The following image shows an illustration of the branches on changing commit his
 
 ## Releases
 
-Both Yii 2 Framework and official extension projects follow the above versioning and branching policies.
-Framework and official extension projects are released independently of each other, i.e. version number mismatch between framework and extension is expected.
-The Application Templates are always released together with the framework.
+Framework and official extension projects are released independently of each other, i.e. version number mismatch between
+framework and extension is expected. The Application Templates are always released together with the framework.
 
-The release cycles described above only apply to the core framework.
-Extensions are released on demand.
-It is likely that an extension has no new releases for a very long time because it does not receive any bug fixes or enhancements.
+The release cycles described above only apply to the core framework. Extensions are released on demand.
+It is likely that an extension has no new releases for a very long time because it does not receive any bug fixes
+or enhancements.