tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 12:05:37 +00:00
Code Issues Projects Releases Wiki Activity

Deprecation docs

Browse Source
This commit is contained in:
Ingo Schommer 2013-03-20 10:20:27 +01:00
parent 52ffb307a7
commit 05689a9421
1 changed files with 16 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/en/misc/release-process.md
View File

@ -85,7 +85,7 @@ micro release.
## Deprecation ## Deprecation
Needs of developers (both on core framework and custom projects) might outgrow the capabilities Needs of developers (both on core framework and custom projects) can outgrow the capabilities
of a certain API. Existing APIs might turn out to be hard to understand, maintain, test or stabilize. of a certain API. Existing APIs might turn out to be hard to understand, maintain, test or stabilize.
In these cases, it is best practice to "refactor" these APIs into something more useful. In these cases, it is best practice to "refactor" these APIs into something more useful.
SilverStripe acknowledges that developers have built a lot of code on top of existing APIs, SilverStripe acknowledges that developers have built a lot of code on top of existing APIs,
@ -94,26 +94,31 @@ so we strive for giving ample warning on any upcoming changes through a "depreca
How to deprecate an API: How to deprecate an API:
* Add a `@deprecated` item to the docblock tag, with a `{@link <class>}` item pointing to the new API to use. * Add a `@deprecated` item to the docblock tag, with a `{@link <class>}` item pointing to the new API to use.
* Update the deprecated code to throw an `E_USER_NOTICE` error, with a message starting with the string 'DEPRECATED:'. * Update the deprecated code to throw a `[api:Deprecation::notice()]` error.
In time, we may use that string to identify deprecation errors, so please ensure that you add this string to the notice level error. * Both the docblock and error message should contain the **target version** where the functionality is removed.
So if you're committing the change to a 3.1 pre-release version, the target version will either be 3.2 or 4.0,
depending on how disruptive the change is.
* Deprecations should just be committed to pre-release branches, ideally before they enter the "beta" phase.
If deprecations are introduced after this point, their target version needs to be increased by one.
* Make sure that the old deprecated function works by calling the new function - don't have duplicated code! * Make sure that the old deprecated function works by calling the new function - don't have duplicated code!
* Mark in which release the function was deprecated (find out next release in the [roadmap](http://open.silverstripe.com/roadmap)), so we can determine when to finally remove it. * The commit message should contain an `API` prefix (see ["commit message format"](/misc/contributing/code#commit-messages))
* Deprecated APIs can be removed after developers had a chance to react to the changes. As a rule of thumb, leave the code with the deprecation warning in for at least three micro releases. Only remove code in a minor or major release.
Here's an example for replacing `Director::isDev()` with a (theoretical) `Env::is_dev()`: Here's an example for replacing `Director::isDev()` with a (theoretical) `Env::is_dev()`:
:::php :::php
/** /**
* Returns true if your are in development mode * Returns true if your are in development mode
* @deprecated (since 2.2.2) Use {@link Env::is_dev()} instead. * @deprecated 3.1 Use {@link Env::is_dev()} instead.
*/ */
public function isDev() { public function isDev() {
user_error("DEPRECATED: Use Env::is_dev() instead.", E_USER_NOTICE); Deprecation::notice('3.1', 'Use Env::is_dev() instead');
return Env::is_dev(); return Env::is_dev();
} }
* Deprecated APIs can be removed after developers had a chance to react to the changes. As a rule of thumb, leave the code with the deprecation warning in for at least three micro releases. Only remove code in a minor or major release. For example:
* Deprecated as of in 2.2.2 This change could be committed to a 3.1.0-alpha2 release, stays deprecated in all following minor releases
* Still deprecated in 2.2.3 (3.1.0-beta1, 3.1.0, 3.1.1), and gets removed from 3.2.0. If the change was introduced in an already
* Still deprecated in 2.2.4 released version (e.g. 3.1.1), the target version becomes 3.2 instead.
* Removed from 2.3.0
## Security Releases ## Security Releases