Establish API deprecation and cleanup policy

[ocramz]

We are currently in a consolidation phase of the library, changing some type signatures and deprecating a bunch of redundant functions and instances. We should be following a consistent policy for cleaning up the namespace after a symbol has been deprecated.

E.g. :

• version A.B.C : DEPRECATE function X
• version A.(B+3*i) or (A+i): delete X (where i is a positive integer e.g. 2) . Depends on how we interpret the PVP.

Examples

Changing implementation

It happens that we might have to change the implementation of a user-facing function for security concerns (e.g sanitize header setting to avoid a potential attack on the client #92 ). In this case we introduce new names, deprecate the old ones and at the end of the deprecation cycle we might want to re-introduce the old names for the new implementation.