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?
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
