Deprecation

Be careful when removing or changing API that others may be depending upon. This is how we will perform deprecations.

In general, a deprecation requires at least three releases to occur. For releases 1, 2, and 3, here is basically what will happen:

1. Deprecation notice is put into code and announced on the developer blog.
2. Replacement API is released, if any
3. Deprecated API is removed from code

NOTE: ANY deprecation notice MUST contain enough information to help API consumers make the transition. If we are replacing an existing feature, it should contain a link to the documentation for the new API. If we are removing an existing feature, it should contain a link to an explanation (possibly here on the wiki), and that explanation should provide links to possible replacements, if any.

Examples

Deprecating Current_User::isLogged(), replacing with Current_User::isAuthenticated()

Release 1

• Add to the top of the Current_User::isLogged() function the line:

trigger_error("Current_User::isLogged() is in deprecation and will be replaced " .
              "with Current_User::isAuthenticated() in Release 2.  See ".
              "http://phpwebsite.appstate.edu/blog/something for more information.",
              E_USER_DEPRECATED);

Release 2

• Create the function Current_User::isAuthenticated()

Release 3

• Remove the function Current_User::isLogged()

Planning to deprecate Current_User soon, but the details have not been worked out yet

Release 1

• Add to the top of Current_User.php, outside the class definition and everything, the line:

trigger_error("Current_User is in deprecation and will be replaced.  Please monitor ".
              "our developer blog for more information.", E_USER_DEPRECATED);

• This will show up when Current_User.php is required or included, to warn the developer that changes are coming.

Release 2

• We now know what the new API will look like, so change that message to give some information:

trigger_error("Current_User is in deprecation and will be replaced.  Please read ".
              "http://phpwebsite.appstate.edu/blog/something for information about ".
              "the new API.", E_USER_DEPRECATED);

Release 3

• Release the new API and announce on the blog, and announce that the old API will be removed in Release 4.

Release 4

• Remove Current_User.php from the repository.

Completely removing the Calendar module with no replacement

Release 1

• In the Calendar module's index.php, add this line:

trigger_error("The Calendar module is in deprecation and will not be replaced  It will ".
              "be completely removed in release 2.  Please read ".
              "http://phpwebsite.appstate.edu/blog/something for more information and ".
              "suggestions for replacement.", E_USER_DEPRECATED);
* Additionally, it may make sense to edit **administrative** user interfaces within the Calendar module to provide user notification that the Calendar will be going away.

#### Release 2
* Modify the descriptions in Release 1 to indicate that Calendar is absolutely no longer supported and that the user should remove it.

#### Release 3
* Remove Calendar from the repository.  Note: I don't recommend actually deleting any data or forcing an uninstall or anything like that, but the error messages from Release 2 are now in there and pushed out to client's installations so they have a clue what is going on.