A deprecation policy

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. +