diff --git a/docs/internals/README.md b/docs/internals/README.md index ac1217f..e1994a9 100644 --- a/docs/internals/README.md +++ b/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 diff --git a/docs/internals/bc.md b/docs/internals/bc.md new file mode 100644 index 0000000..d67c6b5 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/internals/versions.md b/docs/internals/versions.md index 9fabf5d..78aaf6d 100644 --- a/docs/internals/versions.md +++ b/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.