diff options
| -rw-r--r-- | documentation/coding_standards/best_practices.txt | 38 | ||||
| -rw-r--r-- | documentation/coding_standards/deprecation.txt | 36 |
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. |