Re: Migration Docs WAS: Proposal for changes to recovery.conf API

On 12/19/2016 01:29 PM, Peter Eisentraut wrote:
> On 12/16/16 8:52 PM, Robert Haas wrote:
>> > If the explanation is just a few sentences long, I see no reason not
>> > to include it in the release notes.
> As far as I can tell from the latest posted patch, the upgrade
> instructions are
>
> - To trigger recovery, create an empty file recovery.trigger instead of
> recovery.conf.
>
> - All parameters formerly in recovery.conf are now regular
> postgresql.conf parameters. For backward compatibility, recovery.conf
> is read after postgresql.conf, but the parameters can now be put into
> postgresql.conf if desired.

Aren't we changing how some of the parameters work?

>
> Some of that might be subject to patch review, but it's probably not
> going to be much longer than that. So I think that will fit well into
> the usual release notes section.

Changed the subject line of this thread because people are becoming
confused about the new topic.

I'm not talking about *just* the recovery.conf changes. We're making a
lot of changes to 10 which will require user action, and there may be
more before 10 is baked. For example, dealing with the version
numbering change. I started a list of the things we're breaking for 10,
but I don't have it with me at the moment. There's more than 3 things
on it.

And then there's docs for stuff which isn't *required* by upgrading, but
would be a good idea. For example, we'll eventually want a doc on how
to migrate old-style partitioned tables to new-style partitioned tables.

In any case, Peter's response shows *exactly* why I don't want to put
this documentation into the release notes: because people are going to
complain it's too long and want to truncate it. Writing the docs will be
hard enough; if I (or anyone else) has to argue about whether or not
they're too long, I'm just going to drop the patch and walk away.

--
--
Josh Berkus
Red Hat OSAS
(any opinions are my own)