Обсуждение: A deprecation policy
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?
Peter Eisentraut wrote: > 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. I'd prefer to have the upgrade tool convert the old configuration file, comment out max_fsm_* for example. The upgrade tool could well print out warnings about config file changes. I think you'll have a better chance of getting the administrators attention when he's running the upgrade tool than by printing warnings to the log. -- Heikki Linnakangas EnterpriseDB http://www.enterprisedb.com
Hi, Peter Eisentraut wrote: > I have been thinking, with a semi-formal deprecation policy, we could > make these decisions with more confidence. +1 (I'm reading this as a very general proposal also targeting C APIs, not only GUCs). > Comments? With the proposed policy we'd have to recommend users to upgrade in steps of at least every 2nd release for these obsoleteness and deprecation warnings to have any effect. However, I'm often seeing users taking pretty large steps like upgrading from 7.4 to 8.3. OTOH those users are certainly prepared for major incompatibilities and prepared to adjust their code. However, the value of 2 in N+2 is certainly debatable. Regards Markus Wanner
On Wed, Feb 11, 2009 at 2:47 AM, Peter Eisentraut <peter_e@gmx.net> wrote: > 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! This is a very good idea. ...Robert
On Wed, 11 Feb 2009 09:47:25 +0200 Peter Eisentraut <peter_e@gmx.net> wrote: > 1. In release N, an interface is declared "obsolete", which means that > [...] > 2. In release N+1, obsolete interfaces are declared "deprecated", which I like the idea but aren't these two terms reversed? In fact, isn't "obsolete" your third stage? Certainly "obsolete" suggests that it can't be used any longer. I'm not sure what the second stage should be called in that case though. Also, does the progression through releases have to be absolute? Can something stay in "deprecated" for two releases if it is felt that people need more time? > 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. Yes. > 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. But whatever works in 8.6 would also have to work in 8.4, right? We can't call something "deprecated" or "obsolete" without allowing the user to update their code/configuration right away. > 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. As long as they can remove the item giving the warning right away. -- D'Arcy J.M. Cain <darcy@druid.net> | Democracy is three wolves http://www.druid.net/darcy/ | and a sheep voting on +1 416 425 1212 (DoD#0082) (eNTP) | what's for dinner.
>>> "D'Arcy J.M. Cain" <darcy@druid.net> wrote: > On Wed, 11 Feb 2009 09:47:25 +0200 > Peter Eisentraut <peter_e@gmx.net> wrote: >> 1. In release N, an interface is declared "obsolete", which means >> [...] >> 2. In release N+1, obsolete interfaces are declared "deprecated", > > I like the idea but aren't these two terms reversed? In fact, isn't > "obsolete" your third stage? Certainly "obsolete" suggests that it > can't be used any longer. I'm not sure what the second stage should > be called in that case though. I had a similar reaction to the proposed terminology. To me: "Deprecated" means that some other way of doing it is available and preferred. "Obsolescent" (or perhaps "in end of life period") indicates that something is expected to be removed in a future release. "Obsolete" means it used to work, but doesn't anymore. -Kevin
"D'Arcy J.M. Cain" <darcy@druid.net> writes:
> Peter Eisentraut <peter_e@gmx.net> wrote:
>> 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.
> As long as they can remove the item giving the warning right away.
Well, they could only remove the item if it was *already* the case that
it didn't do anything. In general, I think Peter neglected to address
the question of whether "deprecated" objects/functions/etc still have
their original functionality, and where along the path the replacement
functionality starts to exist. It's certainly a bad idea to be throwing
warnings about something that people still have to use.
regards, tom lane
Peter Eisentraut <peter_e@gmx.net> writes:
> I have been thinking, with a semi-formal deprecation policy, we could
> make these decisions with more confidence. My proposed policy goes like
> this:
I've been thinking about this for a couple of hours, and I keep coming
back to the conclusion that if we actually enforced a policy like this
it would kill Postgres development dead. It already takes more than a
year, on average, for a proposal to go from idea to out-in-the-field.
This policy would add another two years onto that for anything that
involved user-visible changes, which is most things. All but the most
persistent developers are simply going to go away and not bother trying
to shepherd their ideas through such a process.
I can see the value of a more formal deprecation policy, but I think
it's gotta have a shorter time constant than this.
regards, tom lane
Peter, > 3. In release N+2, if there were no protests in response to step 2, > deprecated features are removed. The main issue I can see with this is that most production sites only upgrade once every 2-3 years. So they'd tend to miss warnings entirely. > 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. I think the combination of a config file generator (in development now) with a config file checker (something we could use anyway) would take care of any config file issues. I did actually give some thought to a config file converter, but the number of options which are new, changed names, changed names and changed meanings, changed options, or went away makes it an n^2 issue and not really worth solving. Just tell the people to run the new version of the config file generator. The other thing we could use would be clearer documentation on this sort of thing. That is, a single page in the docs which talks about what was depreciated in specific versions. We kinda do this in the release notes, but the notices often aren't that clear and are mixed in with a lot of other stuff. Probably we should just clear this up in the release notes. --Josh
On Wed, 11 Feb 2009, Josh Berkus wrote: > I did actually give some thought to a config file converter, but the number > of options which are new, changed names, changed names and changed meanings, > changed options, or went away makes it an n^2 issue and not really worth > solving. My next big push for pgtune is to backport the pg_settings additions I need to 8.3/8.2/8.1 and assemble a proper settings database for all those versions. Once I finish that, it will be trivial to flag and remove all the parameters that aren't even there anymore, which at least reduces the size of n quite a bit. For the specific case that's been mentioned here, does it even matter if somebody has some old settings for max_fsm_* in their 8.4 postgresql.conf file? Ditto for other deprecated parameters like bgwriter_all_percent. I think that if you ignore everything that just dropped altogether, and just worry about settings whose meaning has changed, the number you'd have left to worry about is much smaller. Unfortunately, those are the hard ones to identify, too. Anyway, I read Peter's suggestion as aiming more at SQL features and API changes, rather than configuration file ones. In trivial cases like sort_mem->work_mem, adding some backward compatibility concessions might make sense. Saddling GUC changes with any restrctions beyond what happens to be easy seems pretty impractical. -- * Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD
Greg Smith <gsmith@gregsmith.com> writes:
> Anyway, I read Peter's suggestion as aiming more at SQL features and API
> changes, rather than configuration file ones. In trivial cases like
> sort_mem->work_mem, adding some backward compatibility concessions might
> make sense.
[ rolls eyes ... ]
$ psql regression
psql (8.4devel)
Type "help" for help.
regression=# set sort_mem = 100;
SET
regression=# show sort_mem;work_mem
----------100kB
(1 row)
regression=#
It's not like we go out of our way to break applications; if there's an
easy compatibility workaround, we generally provide it. In particular
I think that Peter's proposal is mainly thinking about cases where it's
practical to provide a "deprecated" feature and its replacement behavior
concurrently --- at worst being able to switch between one and the other
via a GUC or some such. The hard part, and the question that's missing
from this discussion, is exactly what we'll do when backwards
compatibility is impractical (for whatever size of "impractical" suits
you; there is *always* going to be a point where it's not worth it).
Peter's proposal appears to require that changes in that category have
to be agreed to and announced two years before the change is actually
made. Frankly I don't believe that's going to happen. The original
proposer will have lost interest, or the original patch will have
bit-rotted beyond usefulness, or even more likely somebody will want
the patch bad enough to convince us not to wait two years. (Witness
the annual arguments about how feature FOO should go into the current
release because its developer isn't willing to wait *one* year.)
regards, tom lane
Tom Lane wrote: > Peter Eisentraut <peter_e@gmx.net> writes: > > I have been thinking, with a semi-formal deprecation policy, we could > > make these decisions with more confidence. My proposed policy goes like > > this: > > I've been thinking about this for a couple of hours, and I keep coming > back to the conclusion that if we actually enforced a policy like this > it would kill Postgres development dead. It already takes more than a > year, on average, for a proposal to go from idea to out-in-the-field. > This policy would add another two years onto that for anything that > involved user-visible changes, which is most things. All but the most > persistent developers are simply going to go away and not bother trying > to shepherd their ideas through such a process. > > I can see the value of a more formal deprecation policy, but I think > it's gotta have a shorter time constant than this. Agreed. Consider the downside of having to support two different APIs for two releases, and document them. Yuck. There are some cases where a 2-release buffer is warranted, others where it is not. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +