aboutsummaryrefslogtreecommitdiff
path: root/documentation/coding_standards/deprecation.txt
diff options
context:
space:
mode:
authorBrett Profitt <brett.profitt@gmail.com>2011-08-23 09:16:20 -0700
committerBrett Profitt <brett.profitt@gmail.com>2011-08-23 09:16:20 -0700
commit3e1a96cabb228b59021676772daca23b22a026c7 (patch)
tree3ba1cdf9a9d271c39bceac8b8d5c2b78e0d61977 /documentation/coding_standards/deprecation.txt
parent8dc4ca48d1ff5c3800637a463a7b072fb253634e (diff)
parent5ac7727c36392633dc7d1d4a79ee3c5086bd37b6 (diff)
downloadelgg-3e1a96cabb228b59021676772daca23b22a026c7.tar.gz
elgg-3e1a96cabb228b59021676772daca23b22a026c7.tar.bz2
Merge branch 'master' of github.com:Elgg/Elgg
Conflicts: engine/lib/views.php
Diffstat (limited to 'documentation/coding_standards/deprecation.txt')
-rw-r--r--documentation/coding_standards/deprecation.txt36
1 files changed, 36 insertions, 0 deletions
diff --git a/documentation/coding_standards/deprecation.txt b/documentation/coding_standards/deprecation.txt
new file mode 100644
index 000000000..370090138
--- /dev/null
+++ b/documentation/coding_standards/deprecation.txt
@@ -0,0 +1,36 @@
+*** DEPRECATING APIs ***
+
+Occasionally, functions and classes must be deprecated in favor of newer
+replacements. Since 3rd party plugin authors rely on a consistent API,
+backward compatibility must be maintained, but will not be maintained
+indefinitely as plugin authors are expected to properly update their
+plugins. In order to maintain backward compatibility, deprecated APIs will
+follow these guidelines:
+
+* Incompatible API changes cannot occur between bugfix versions
+ (1.6.0 - 1.6.1).
+
+* API changes between minor versions (1.6 - 1.7) must maintain backward
+ compatibility for at least 2 minor versions. (1.7 and 1.8. See
+ procedures, below.)
+
+* Bugfixes that change the API cannot be included in bugfix versions.
+
+* API changes between major versions (1.0 - 2.0) can occur without regard to
+ backward compatibility.
+
+The procedure for deprecating an API is as follows:
+
+* The first minor version (1.7) with a deprecated API must include a wrapper
+ function/class (or otherwise appropriate means) to maintain backward
+ compatibility, including any bugs in the original function/class.
+ This compatibility layer uses elgg_deprecated_notice('...', 1.7) to log
+ that the function is deprecated.
+
+* The second minor version (1.8) maintains the backward compatibility
+ layer, but elgg_deprecated_notice() will produce a visible warning.
+
+* The third minor version (1.9) removes the compatibility layer. Any use of
+ the deprecated API should be corrected before this.
+
+The general timeline for two minor releases is 8 to 12 months.