pulled deprecation guidelines out of general best practices

diff --git a/documentation/coding_standards/best_practices.txt b/documentation/coding_standards/best_practices.txt
index 68dcce38b13fbd5bfe19d4f417bfc19f81b2d0f2..069ac42aa807fbe338131a38e5f22a5b284cfeb1 100644 (file)
--- 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 (file)
index 0000000..3700901
--- /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.