aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorcash <cash.costello@gmail.com>2011-07-03 09:04:52 -0400
committercash <cash.costello@gmail.com>2011-07-03 09:04:52 -0400
commit0b3e6b6ed28742c29df5d09476b50fbce7f36dbb (patch)
tree648411a320183488300b9cbe77a90289be7cf22f
parent807ae30cb037b827319b924994952daf57db2a40 (diff)
downloadelgg-0b3e6b6ed28742c29df5d09476b50fbce7f36dbb.tar.gz
elgg-0b3e6b6ed28742c29df5d09476b50fbce7f36dbb.tar.bz2
pulled deprecation guidelines out of general best practices
-rw-r--r--documentation/coding_standards/best_practices.txt38
-rw-r--r--documentation/coding_standards/deprecation.txt36
2 files changed, 36 insertions, 38 deletions
diff --git a/documentation/coding_standards/best_practices.txt b/documentation/coding_standards/best_practices.txt
index 68dcce38b..069ac42aa 100644
--- a/documentation/coding_standards/best_practices.txt
+++ b/documentation/coding_standards/best_practices.txt
@@ -56,41 +56,3 @@ work for developers, which means happier, more productive developers.
* Commit effectively: Err on the side of atomic commits. One revision with
many changes is scary.
-
-
-*** 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.
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.