A deprecation policy - Mailing list pgsql-hackers

We often discuss changing user-visible behavior of various kinds and are 
usually clueless on the question of "someone might rely on this" or "how 
many people are still using this" etc.  Still, it is clearly often 
useful to revise interfaces from time to time.

I have been thinking, with a semi-formal deprecation policy, we could 
make these decisions with more confidence.  My proposed policy goes like 
this:

1. In release N, an interface is declared "obsolete", which means that 
we consider that it is no longer recommended to use the interface; 
better alternatives are usually available.  An obsolete interface is 
marked as such in the documentation, and the list of obsoleted 
interfaces is also listed in the release notes.

(In certain cases, it may be permissible to skip this step if the 
interface was built as a workaround in the first place and the 
obsoletion is obvious.)

2. In release N+1, obsolete interfaces are declared "deprecated", which 
means that users really shouldn't use the interface and are urged to 
change their code as soon as possible.  Through some configuration 
mechanism, where technically possible, using deprecated features draws a 
warning or an error (warning on by default).  Deprecated features are 
also marked in the documentation and release notes.

3. In release N+2, if there were no protests in response to step 2, 
deprecated features are removed.

This approach gives users and developers the ability to clearly plan 
ahead and take necessary actions.  Usually, you'd have about 2 years to 
react.

Also, consider that we want to get in-place upgrade working, so 
essential interfaces such as basic commands and configuration files 
should at least be able to limp along after being moved to version N+1.

Examples:

Removing implicit casts (with hindsight):  Release N: Declare certain 
casts obsolete.  Release N+1: Raise deprecation warning when cast 
function invoked implicitly.  Release N+2: Remove.

Removing SQL_interitance option: Release: Declare obsolete.  Release 
N+1: Deprecation warning.  Release N+2: Remove.

Altering semantics of log_filename without placeholder (under 
discussion):  Release 8.4: Declare current behavior obsolete.  Release 
8.5: Deprecation warning.  Release 8.6: Implement whatever new behavior 
we like.

I would also extend this system to removed configuration settings, e.g., 
max_fsm_*.  We should make these deprecated for one release, so (1) 
configuration files can be upgraded without manual work (relevant to 
in-place upgrade), and (2) users are alerted that their carefully 
crafted configuration might need a review.

Comments?