*** 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.