Help text for pg_basebackup -R

Started by Magnus Haganderalmost 9 years ago7 messages

magnus@hagander.net

almost 9 years ago

1 attachment(s)

The current help text for pg_basebackup -R is "write recovery.conf after
backup".

This says nothing about what it actually does. I've had a number of people
ask me now why that's not default "because you need a recovery.conf to
restore from backup". The point being that it doesn't say anything about
the fact that it writes the file *for replication*. The help page does, but
not the message.

I propose a new message per the attached patch.

Comments?

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

Attachments:

pg_basebackup_recovery_help.patchtext/x-patch; charset=US-ASCII; name=pg_basebackup_recovery_help.patchDownload

diff --git a/src/bin/pg_basebackup/pg_basebackup.c b/src/bin/pg_basebackup/pg_basebackup.c
index 0c82bc9..9020fb1 100644
--- a/src/bin/pg_basebackup/pg_basebackup.c
+++ b/src/bin/pg_basebackup/pg_basebackup.c
@@ -337,7 +337,7 @@ usage(void)
 	printf(_("  -r, --max-rate=RATE    maximum transfer rate to transfer data directory\n"
 	  "                         (in kB/s, or use suffix \"k\" or \"M\")\n"));
 	printf(_("  -R, --write-recovery-conf\n"
-			 "                         write recovery.conf after backup\n"));
+			 "                         write recovery.conf for replication\n"));
 	printf(_("  -S, --slot=SLOTNAME    replication slot to use\n"));
 	printf(_("      --no-slot          prevent creation of temporary replication slot\n"));
 	printf(_("  -T, --tablespace-mapping=OLDDIR=NEWDIR\n"

Alvaro Herrera

alvherre@2ndquadrant.com

almost 9 years ago

In reply to: Magnus Hagander (#1)

Re: Help text for pg_basebackup -R

Magnus Hagander wrote:

printf(_("  -R, --write-recovery-conf\n"
-			 "                         write recovery.conf after backup\n"));
+			 "                         write recovery.conf for replication\n"));
printf(_("  -S, --slot=SLOTNAME    replication slot to use\n"));

LGTM.

--
ï¿½lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Magnus Hagander

magnus@hagander.net

almost 9 years ago

In reply to: Alvaro Herrera (#2)

Re: Help text for pg_basebackup -R

On Wednesday, February 15, 2017, Alvaro Herrera <alvherre@2ndquadrant.com>
wrote:

Magnus Hagander wrote:

printf(_(" -R, --write-recovery-conf\n"
- " write recovery.conf

after backup\n"));

+ " write recovery.conf for

replication\n"));

printf(_(" -S, --slot=SLOTNAME replication slot to use\n"));

LGTM.

I'm guessing if we backpatch something like that, it would cause issues for
translations, right? So we should make it head only?

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

Alvaro Herrera

alvherre@2ndquadrant.com

almost 9 years ago

In reply to: Magnus Hagander (#3)

Re: Help text for pg_basebackup -R

Magnus Hagander wrote:

On Wednesday, February 15, 2017, Alvaro Herrera <alvherre@2ndquadrant.com>
wrote:

Magnus Hagander wrote:

printf(_(" -R, --write-recovery-conf\n"
- " write recovery.conf

after backup\n"));

+ " write recovery.conf for

replication\n"));

printf(_(" -S, --slot=SLOTNAME replication slot to use\n"));

LGTM.

I'm guessing if we backpatch something like that, it would cause issues for
translations, right? So we should make it head only?

We've had the argument a number of times. My stand is that many
translators are active in the older branches, so this update would be
caught there too; and even if not, an updated English message is better
than an outdated native-language message.

Now, that's been argued in the context of a bug fix that introduces new
messages or changed an existing message for other reasons. I'm not sure
how strongly do we think it applies for a change that's *only* about
updating a message. I'm +0.5 on back-patching the change in this case.

--
ï¿½lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Stephen Frost

sfrost@snowman.net

almost 9 years ago

In reply to: Alvaro Herrera (#4)

Re: Help text for pg_basebackup -R

* Alvaro Herrera (alvherre@2ndquadrant.com) wrote:

Magnus Hagander wrote:

On Wednesday, February 15, 2017, Alvaro Herrera <alvherre@2ndquadrant.com>
wrote:

Magnus Hagander wrote:

printf(_(" -R, --write-recovery-conf\n"
- " write recovery.conf

after backup\n"));

+ " write recovery.conf for

replication\n"));

printf(_(" -S, --slot=SLOTNAME replication slot to use\n"));

LGTM.

I'm guessing if we backpatch something like that, it would cause issues for
translations, right? So we should make it head only?

We've had the argument a number of times. My stand is that many
translators are active in the older branches, so this update would be
caught there too; and even if not, an updated English message is better
than an outdated native-language message.

That makes sense to me, at least, so +1, for my part. Of course, I'm
not a translation-using user, but I have heard from people when I've
spoken in other countries that a correct english message is better than
outdated native-language messages, and further, that having the English
message makes it easier to get Google results.

Thanks!

Stephen

Tom Lane

tgl@sss.pgh.pa.us

almost 9 years ago

In reply to: Stephen Frost (#5)

Re: Help text for pg_basebackup -R

Stephen Frost <sfrost@snowman.net> writes:

* Alvaro Herrera (alvherre@2ndquadrant.com) wrote:

Magnus Hagander wrote:

I'm guessing if we backpatch something like that, it would cause issues for
translations, right? So we should make it head only?

We've had the argument a number of times. My stand is that many
translators are active in the older branches, so this update would be
caught there too; and even if not, an updated English message is better
than an outdated native-language message.

That makes sense to me, at least, so +1, for my part.

Yeah, if the existing message text is actually wrong or misleading,
we should back-patch. I'm not sure I would do that if it's just a
cosmetic improvement. In this particular case, +1.

regards, tom lane

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Magnus Hagander

magnus@hagander.net

almost 9 years ago

In reply to: Tom Lane (#6)

Re: Help text for pg_basebackup -R

On Fri, Feb 17, 2017 at 5:21 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Stephen Frost <sfrost@snowman.net> writes:

* Alvaro Herrera (alvherre@2ndquadrant.com) wrote:

Magnus Hagander wrote:

I'm guessing if we backpatch something like that, it would cause

issues for

translations, right? So we should make it head only?

We've had the argument a number of times. My stand is that many
translators are active in the older branches, so this update would be
caught there too; and even if not, an updated English message is better
than an outdated native-language message.

That makes sense to me, at least, so +1, for my part.

Yeah, if the existing message text is actually wrong or misleading,
we should back-patch. I'm not sure I would do that if it's just a
cosmetic improvement. In this particular case, +1.

OK. Applied and backpatched.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/