Re: Proposal for changes to recovery.conf API

On Sat, Dec 17, 2016 at 10:34 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Sat, Dec 17, 2016 at 02:52:41PM +0100, Magnus Hagander wrote:
> > The point is that the documentation about the recovery.conf changes
> in
> > Postgres are only interesting to people migrating to Postgres 10,
> i.e.
> > this is not quality documentation for someone going from Postgres 10
> to
> > Postgres 11.
> >
> >
> >
> > They will also be interesting to people going from 9.4 to 11, or from
> 9.3 to
> > 12. Or from 9.5 to 13.
> >
> > They only become uninteresting when we stop supporting 9.6 which is the
> last
> > version that didn't have that functionality.
>
> No, they become uninteresting to anyone who has passed Postgres 10. I
> would argue they are still required to be around even after we stop
> supporting Postgres 9.6 because we know everyone will not upgrade off of
> supported releases once we stop supporting them. This means we can
> effectively never remove the information.
>

This is true, but I think it's also safe to say that it's acceptable that
if you are upgrading from an unsupported version you need to read more than
one set of documentation -- one set to get to a supported one, and one get
on from there.

> Right now if you migrate from Postgres 8.0 to Postgres 9.6, all the
> information you need is in the 9.6 documentation. If you were to remove
> migration details from 8.4 to 9.0 they would have to look at the 9.0
> docs to get a full picture of how to migrate.
>

In fairness, all the information you need is definitely not in the
documentation. You have all the release notes, that is true. But for a lot
of people and in the case of a lot of features, that is not at all enough
information. But it's true in the sense that it's just as much information
as you would've had if you'd done the incremental steps of upgrading,
because we didn't purge anything.

> Again, I am fine putting this as a subsection of the release notes, but
> let's not pretend it is some extra section we can remove in five years.

Depends on what we decide to do about it, but sure, it could certainly turn
into another section that we keep around (whether as part of the release
notes, or as a separate "upgrade steps" section or something).

//Magnus