On Wed, Apr 6, 2016 at 6:42 AM, Noah Misch <n...@leadboat.com> wrote:
> On Tue, Apr 05, 2016 at 08:15:16PM +0200, Magnus Hagander wrote: > > I've pushed this version, and also added the item from the Brussels > > developer meeting to actually rewrite the main backup docs to the open > > items so they are definitely not forgotten for 9.6. > > Here's that PostgreSQL 9.6 open item: > > * Update of backup documentation (assigned to Bruce at [ > https://wiki.postgresql.org/wiki/FOSDEM/PGDay_2016_Developer_Meeting > Brussels Developer Meeting], but others are surely allowed to work on it as > well) > ** Made required by 7117685461af50f50c03f43e6a622284c8d54694 since the > current documentation is now incorrect > > Unless Bruce endorsed this development strategy, I think it unfair for > commit > 7117685 to impose a deadline on his backup.sgml project. Did commit > 7117685 > I agree that's a horrible wording. What it meant to imply was a deadline for *me* to help take that off Bruce's shoulders before then while also opening the doors for others to work on it should they want. Re-reading it now I can see that's not at all what it says. I'll reword (or rather, remove most of that, since it's been discussed separately and doesn't actually need to go on the open items list which is a list and not a discussion) (And yes, I chatted with Bruce about doing that weeks ago, so he knows well about it - just that's not what the entry says). > indeed make the documentation "incorrect?" Coverage in the Backup and > Restore > chapter would be a good thing, but I don't think that gap alone makes > 7117685, > with its reference-only documentation, incorrect. Did 7117685 impair > documentation in any other respect? Probably incomplete is a better word there as well. > Incidentally, I'm not clear on the extent of Bruce's plans to change backup > documentation. Relevant meeting note fragment: > > Magnus: We need a new robust API fornon-exclusive backups > Simon: Keep but deprecate the existing API. > Need to find a better way to ensure users have the required xlog in > backups > Craig: Our docs are in the wrong order. pg_basebackup should be first, > ahead of manual methods. > Action point: Re-arrange backup docs page (Bruce) > > The chapter already does describe pg_basebackup before describing > pg_start_backup; what else did the plan entail? > > Recommending people to primarily use tried and tested ways of doing backups (including a reference to a list, probably on the wiki, of known external tools that "do things the right way", such as backrest or barman) rather than focusing on examples that aren't necessarily even correct, and certainly not complete. Mentioning the actual problems of exclusive base backups. (And obviously talk about how using pg_start_backup/pg_stop_backup now makes it possible to do "low level" backups without the risks of exclusive backups -- which is the "incomplete" part from my note. More clearly outlining backup vs dump, and possibly (I can't actually remember if we decided the second step) put base backups before pg_dump since the topic is backups. -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/
