Update HINT messages to conform to new standard detailed in CODING.md.

CODING.md

@@ -123,6 +123,12 @@ if (condition)
 }
 ```
 
+#### Hints, Warnings, and Errors
+
+Hints are to be formatted with capitalized `HINT:` followed by a space and a sentence. The sentence shall only begin with a capital letter if the first word is an acronym (e.g. TLS) or a proper name (e.g. PostgreSQL). The sentence must end with a period, question mark or exclamation point as appropriate.
+
+Warning and errors shall be lowercase with the exceptions for proper names and acronyms and end without punctuation.
+
 ## Language Elements
 
 ### Data Types

doc/xml/coding.xml

@@ -162,6 +162,14 @@ if (condition)
 }
                 </code-block>
             </section>
+
+            <section id="hints-warnings-errors">
+                <title>Hints, Warnings, and Errors</title>
+
+                <p>Hints are to be formatted with capitalized <id>HINT:</id> followed by a space and a sentence. The sentence shall only begin with a capital letter if the first word is an acronym (e.g. TLS) or a proper name (e.g. PostgreSQL). The sentence must end with a period, question mark or exclamation point as appropriate.</p>
+
+                <p>Warning and errors shall be lowercase with the exceptions for proper names and acronyms and end without punctuation.</p>
+            </section>
         </section>
     </section>
 

lib/pgBackRest/Archive/Info.pm

@@ -120,7 +120,7 @@ sub new
         }
         elsif ($iResult == ERROR_CRYPTO && $strResultMessage =~ "^unable to flush")
         {
-            confess &log(ERROR, "unable to parse '$strArchiveInfoFile'\nHINT: Is or was the repo encrypted?", $iResult);
+            confess &log(ERROR, "unable to parse '$strArchiveInfoFile'\nHINT: is or was the repo encrypted?", $iResult);
         }
         else
         {
@@ -412,7 +412,7 @@ sub reconstruct
         if (!storageRepo()->encryptionValid(storageRepo()->encrypted($strArchiveFilePath)))
         {
             confess &log(ERROR, "encryption incompatible for '$strArchiveFilePath'" .
-                "\nHINT: Is or was the repo encrypted?", ERROR_CRYPTO);
+                "\nHINT: is or was the repo encrypted?", ERROR_CRYPTO);
         }
 
         # If the file is encrypted, then the passphrase from the info file is required, else getEncryptionKeySub returns undefined

lib/pgBackRest/Backup/Info.pm

@@ -165,7 +165,7 @@ sub new
         }
         elsif ($iResult == ERROR_CRYPTO && $strResultMessage =~ "^unable to flush")
         {
-            confess &log(ERROR, "unable to parse '$strBackupInfoFile'\nHINT: Is or was the repo encrypted?", $iResult);
+            confess &log(ERROR, "unable to parse '$strBackupInfoFile'\nHINT: is or was the repo encrypted?", $iResult);
         }
         else
         {

lib/pgBackRest/Common/Ini.pm

@@ -188,7 +188,7 @@ sub loadVersion
     else
     {
         confess &log(ERROR, "unable to parse '$self->{strFileName}" . ($bCopy ? INI_COPY_EXT : '') . "'" .
-            "\nHINT: Is or was the repo encrypted?", ERROR_CRYPTO);
+            "\nHINT: is or was the repo encrypted?", ERROR_CRYPTO);
     }
 
     return defined($self->{oContent});

lib/pgBackRest/Db.pm

@@ -707,7 +707,7 @@ sub configValidate
                 " '${strDbVersion}' and " . cfgOptionName(CFGOPT_PG_PATH) . " '$self->{strDbPath}' read from" .
                 " '$self->{strDbPath}/" . DB_FILE_PGCONTROL . "'\n" .
             "HINT: the " . cfgOptionName(CFGOPT_PG_PATH) . " and " . cfgOptionName(CFGOPT_PG_PORT) .
-                " settings likely reference different clusters",
+                " settings likely reference different clusters.",
             ERROR_DB_MISMATCH);
     }
 

src/command/archive/common.c

@@ -251,7 +251,7 @@ walPath(const String *walFile, const String *pgPath, const String *command)
             THROW_FMT(
                 OptionRequiredError,
                 "option '" CFGOPT_PG1_PATH "' must be specified when relative wal paths are used\n"
-                    "HINT: Is %%f passed to %s instead of %%p?\n"
+                    "HINT: is %%f passed to %s instead of %%p?\n"
                     "HINT: PostgreSQL may pass relative paths even with %%p depending on the environment.",
                 strPtr(command));
         }

src/command/check/check.c

@@ -62,8 +62,8 @@ cmdCheck(void)
                 THROW_FMT(
                     ArchiveTimeoutError,
                     "WAL segment %s was not archived before the %" PRIu64 "ms timeout\n"
-                        "HINT: Check the archive_command to ensure that all options are correct (especially --stanza).\n"
+                        "HINT: check the archive_command to ensure that all options are correct (especially --stanza).\n"
-                        "HINT: Check the PostgreSQL server log for errors.",
+                        "HINT: check the PostgreSQL server log for errors.",
                     strPtr(walSegment), archiveTimeout);
             }
         }

src/command/check/common.c

@@ -32,7 +32,7 @@ checkDbConfig(const unsigned int pgVersion, const unsigned int dbIdx, const unsi
     {
         THROW_FMT(
             DbMismatchError, "version '%s' and path '%s' queried from cluster do not match version '%s' and '%s' read from '%s/"
-            PG_PATH_GLOBAL "/" PG_FILE_PGCONTROL "'\nHINT: the %s and %s settings likely reference different clusters",
+            PG_PATH_GLOBAL "/" PG_FILE_PGCONTROL "'\nHINT: the %s and %s settings likely reference different clusters.",
             strPtr(pgVersionToStr(dbVersion)), strPtr(dbPath), strPtr(pgVersionToStr(pgVersion)), strPtr(cfgOptionStr(pgPath)),
             strPtr(cfgOptionStr(pgPath)), cfgOptionName(pgPath), cfgOptionName(cfgOptPgPort + (dbIdx - 1)));
     }

src/command/info/info.c

@@ -321,7 +321,7 @@ stanzaInfoList(const String *stanza, StringList *stanzaList)
             THROW_FMT(
                 CryptoError,
                 "%s\n"
-                "HINT: use option --stanza if encryption settings are different for the stanza than the global settings",
+                "HINT: use option --stanza if encryption settings are different for the stanza than the global settings.",
                 errorMessage());
         }
         TRY_END();

src/config/load.c

@@ -226,9 +226,9 @@ cfgLoadUpdateOption(void)
         THROW_FMT(
             OptionInvalidValueError,
             "'%s' is not valid for option '" CFGOPT_REPO1_S3_BUCKET "'"
-                "\nHINT: RFC-2818 forbids dots in wildcard matches"
+                "\nHINT: RFC-2818 forbids dots in wildcard matches."
-                "\nHINT: TLS/SSL verification cannot proceed with this bucket name"
+                "\nHINT: TLS/SSL verification cannot proceed with this bucket name."
-                "\nHINT: remove dots from the bucket name",
+                "\nHINT: remove dots from the bucket name.",
             strPtr(cfgOptionStr(cfgOptRepoS3Bucket)));
     }
 

src/perl/embed.auto.c

@@ -465,7 +465,7 @@ static const EmbeddedModule embeddedModule[] =
             "}\n"
             "elsif ($iResult == ERROR_CRYPTO && $strResultMessage =~ \"^unable to flush\")\n"
             "{\n"
-            "confess &log(ERROR, \"unable to parse '$strArchiveInfoFile'\\nHINT: Is or was the repo encrypted?\", $iResult);\n"
+            "confess &log(ERROR, \"unable to parse '$strArchiveInfoFile'\\nHINT: is or was the repo encrypted?\", $iResult);\n"
             "}\n"
             "else\n"
             "{\n"
@@ -707,7 +707,7 @@ static const EmbeddedModule embeddedModule[] =
             "if (!storageRepo()->encryptionValid(storageRepo()->encrypted($strArchiveFilePath)))\n"
             "{\n"
             "confess &log(ERROR, \"encryption incompatible for '$strArchiveFilePath'\" .\n"
-            "\"\\nHINT: Is or was the repo encrypted?\", ERROR_CRYPTO);\n"
+            "\"\\nHINT: is or was the repo encrypted?\", ERROR_CRYPTO);\n"
             "}\n"
             "\n\n"
             "my $oFileIo = storageRepo()->openRead(\n"
@@ -2449,7 +2449,7 @@ static const EmbeddedModule embeddedModule[] =
             "}\n"
             "elsif ($iResult == ERROR_CRYPTO && $strResultMessage =~ \"^unable to flush\")\n"
             "{\n"
-            "confess &log(ERROR, \"unable to parse '$strBackupInfoFile'\\nHINT: Is or was the repo encrypted?\", $iResult);\n"
+            "confess &log(ERROR, \"unable to parse '$strBackupInfoFile'\\nHINT: is or was the repo encrypted?\", $iResult);\n"
             "}\n"
             "else\n"
             "{\n"
@@ -3920,7 +3920,7 @@ static const EmbeddedModule embeddedModule[] =
             "else\n"
             "{\n"
             "confess &log(ERROR, \"unable to parse '$self->{strFileName}\" . ($bCopy ? INI_COPY_EXT : '') . \"'\" .\n"
-            "\"\\nHINT: Is or was the repo encrypted?\", ERROR_CRYPTO);\n"
+            "\"\\nHINT: is or was the repo encrypted?\", ERROR_CRYPTO);\n"
             "}\n"
             "\n"
             "return defined($self->{oContent});\n"
@@ -7344,7 +7344,7 @@ static const EmbeddedModule embeddedModule[] =
             "\" '${strDbVersion}' and \" . cfgOptionName(CFGOPT_PG_PATH) . \" '$self->{strDbPath}' read from\" .\n"
             "\" '$self->{strDbPath}/\" . DB_FILE_PGCONTROL . \"'\\n\" .\n"
             "\"HINT: the \" . cfgOptionName(CFGOPT_PG_PATH) . \" and \" . cfgOptionName(CFGOPT_PG_PORT) .\n"
-            "\" settings likely reference different clusters\",\n"
+            "\" settings likely reference different clusters.\",\n"
             "ERROR_DB_MISMATCH);\n"
             "}\n"
             "\n\n"

test/lib/pgBackRestTest/Module/Common/CommonIniPerlTest.pm

@@ -290,14 +290,14 @@ sub run
 
         $self->testException(sub {new pgBackRest::Common::Ini($strTestFile)}, ERROR_CRYPTO,
             "unable to parse '$strTestFileCopy'" .
-            "\nHINT: Is or was the repo encrypted?");
+            "\nHINT: is or was the repo encrypted?");
 
         # Prepend encryption Magic signature to main to simulate encryption
         executeTest('echo "' . CIPHER_MAGIC . '$(cat ' . $strTestFile . ')" > ' . $strTestFile);
 
         $self->testException(sub {new pgBackRest::Common::Ini($strTestFile)}, ERROR_CRYPTO,
             "unable to parse '$strTestFile'" .
-            "\nHINT: Is or was the repo encrypted?");
+            "\nHINT: is or was the repo encrypted?");
     }
 
     ################################################################################################################################

test/lib/pgBackRestTest/Module/Info/InfoInfoArchivePerlTest.pm

@@ -110,7 +110,7 @@ sub run
 
         $self->testException(sub {$oArchiveInfo->reconstruct(PG_VERSION_94, $self->dbSysId(PG_VERSION_94))}, ERROR_CRYPTO,
             "encryption incompatible for '$strArchiveFile'" .
-            "\nHINT: Is or was the repo encrypted?");
+            "\nHINT: is or was the repo encrypted?");
 
         executeTest('sudo rm ' . $strArchiveFile);
 
@@ -206,7 +206,7 @@ sub run
 
         $self->testException(sub {new pgBackRest::Archive::Info(storageRepo()->pathGet(STORAGE_REPO_ARCHIVE))}, ERROR_CRYPTO,
             "unable to parse '$strFile'" .
-            "\nHINT: Is or was the repo encrypted?");
+            "\nHINT: is or was the repo encrypted?");
 
         # Remove the archive info files
         executeTest('sudo rm ' . $oArchiveInfo->{strFileName} . '*');

test/lib/pgBackRestTest/Module/Info/InfoInfoBackupPerlTest.pm

@@ -215,7 +215,7 @@ sub run
 
         $self->testException(sub {new pgBackRest::Backup::Info(storageRepo()->pathGet(STORAGE_REPO_BACKUP))}, ERROR_CRYPTO,
             "unable to parse '$strFile'" .
-            "\nHINT: Is or was the repo encrypted?");
+            "\nHINT: is or was the repo encrypted?");
 
         # Create encrypted files, change the passphrase and attempt to load - ensure flush error returned as parse error
         #---------------------------------------------------------------------------------------------------------------------------
@@ -255,7 +255,7 @@ sub run
 
         $self->testException(sub {new pgBackRest::Backup::Info(storageRepo()->pathGet(STORAGE_REPO_BACKUP))}, ERROR_CRYPTO,
             "unable to parse '" . $oBackupInfo->{strFileName} . "'" .
-            "\nHINT: Is or was the repo encrypted?");
+            "\nHINT: is or was the repo encrypted?");
     }
 }
 

test/src/module/command/archiveCommonTest.c

@@ -182,7 +182,7 @@ testRun(void)
         TEST_ERROR(
             walPath(strNew("relative/path"), NULL, strNew("test")), OptionRequiredError,
             "option 'pg1-path' must be specified when relative wal paths are used\n"
-                "HINT: Is %f passed to test instead of %p?\n"
+                "HINT: is %f passed to test instead of %p?\n"
                 "HINT: PostgreSQL may pass relative paths even with %p depending on the environment.");
     }
 

test/src/module/command/archivePushTest.c

@@ -195,7 +195,7 @@ testRun(void)
         TEST_ERROR(
             cmdArchivePush(), OptionRequiredError,
             "option 'pg1-path' must be specified when relative wal paths are used"
-            "\nHINT: Is %f passed to archive-push instead of %p?"
+            "\nHINT: is %f passed to archive-push instead of %p?"
             "\nHINT: PostgreSQL may pass relative paths even with %p depending on the environment.");
 
         // Create pg_control and archive.info

test/src/module/command/checkTest.c

@@ -72,8 +72,8 @@ testRun(void)
         TEST_ERROR(
             cmdCheck(), ArchiveTimeoutError,
             "WAL segment 000000010000000100000001 was not archived before the 500ms timeout\n"
-            "HINT: Check the archive_command to ensure that all options are correct (especially --stanza).\n"
+            "HINT: check the archive_command to ensure that all options are correct (especially --stanza).\n"
-            "HINT: Check the PostgreSQL server log for errors.");
+            "HINT: check the PostgreSQL server log for errors.");
 
         // Create WAL segment
         Buffer *buffer = bufNew(16 * 1024 * 1024);
@@ -145,7 +145,7 @@ testRun(void)
             checkDbConfig(PG_VERSION_92, 1, PG_VERSION_94, pg1Path),
             DbMismatchError, "version '%s' and path '%s' queried from cluster do not match version '%s' and '%s'"
             " read from '%s/" PG_PATH_GLOBAL "/" PG_FILE_PGCONTROL "'\n"
-            "HINT: the pg1-path and pg1-port settings likely reference different clusters",
+            "HINT: the pg1-path and pg1-port settings likely reference different clusters.",
             strPtr(pgVersionToStr(PG_VERSION_94)), strPtr(pg1Path), strPtr(pgVersionToStr(PG_VERSION_92)), strPtr(pg1Path),
             strPtr(pg1Path));
 
@@ -154,7 +154,7 @@ testRun(void)
             checkDbConfig(PG_VERSION_92, 1, PG_VERSION_92, strNew("bogus/path")),
             DbMismatchError, "version '%s' and path '%s' queried from cluster do not match version '%s' and '%s'"
             " read from '%s/" PG_PATH_GLOBAL "/" PG_FILE_PGCONTROL "'\n"
-            "HINT: the pg1-path and pg1-port settings likely reference different clusters",
+            "HINT: the pg1-path and pg1-port settings likely reference different clusters.",
             strPtr(pgVersionToStr(PG_VERSION_92)), "bogus/path", strPtr(pgVersionToStr(PG_VERSION_92)), strPtr(pg1Path),
             strPtr(pg1Path));
     }

test/src/module/command/infoTest.c

@@ -745,7 +745,7 @@ testRun(void)
             "FileMissingError: " STORAGE_ERROR_READ_MISSING "\n"
             "HINT: backup.info cannot be opened and is required to perform a backup.\n"
             "HINT: has a stanza-create been performed?\n"
-            "HINT: use option --stanza if encryption settings are different for the stanza than the global settings",
+            "HINT: use option --stanza if encryption settings are different for the stanza than the global settings.",
             strPtr(backupStanza2Path), strPtr(backupStanza2Path),  strPtr(strNewFmt("%s/backup.info.copy",
             strPtr(backupStanza2Path))));
     }

test/src/module/command/stanzaTest.c

@@ -491,7 +491,7 @@ testRun(void)
         TEST_ERROR_FMT(
             pgValidate(), DbMismatchError, "version '%s' and path '%s' queried from cluster do not match version '%s' and '%s'"
             " read from '%s/" PG_PATH_GLOBAL "/" PG_FILE_PGCONTROL "'\n"
-            "HINT: the pg1-path and pg1-port settings likely reference different clusters",
+            "HINT: the pg1-path and pg1-port settings likely reference different clusters.",
             strPtr(pgVersionToStr(PG_VERSION_92)), strPtr(pg1Path), strPtr(pgVersionToStr(PG_VERSION_91)), strPtr(pg1Path),
             strPtr(pg1Path));
 
@@ -512,7 +512,7 @@ testRun(void)
         TEST_ERROR_FMT(
             pgValidate(), DbMismatchError, "version '%s' and path '%s' queried from cluster do not match version '%s' and '%s'"
             " read from '%s/" PG_PATH_GLOBAL "/" PG_FILE_PGCONTROL
-            "'\nHINT: the pg1-path and pg1-port settings likely reference different clusters",
+            "'\nHINT: the pg1-path and pg1-port settings likely reference different clusters.",
             strPtr(pgVersionToStr(PG_VERSION_92)), strPtr(strNewFmt("%s/pg2", testPath())), strPtr(pgVersionToStr(PG_VERSION_92)),
             strPtr(pg1Path), strPtr(pg1Path));
 

test/src/module/config/loadTest.c

@@ -280,9 +280,9 @@ testRun(void)
         TEST_ERROR(
             harnessCfgLoad(strLstSize(argList), strLstPtr(argList)), OptionInvalidValueError,
             "'bogus.bucket' is not valid for option 'repo1-s3-bucket'"
-                "\nHINT: RFC-2818 forbids dots in wildcard matches"
+                "\nHINT: RFC-2818 forbids dots in wildcard matches."
-                "\nHINT: TLS/SSL verification cannot proceed with this bucket name"
+                "\nHINT: TLS/SSL verification cannot proceed with this bucket name."
-                "\nHINT: remove dots from the bucket name");
+                "\nHINT: remove dots from the bucket name.");
 
         // Invalid bucket name with verification disabled succeeds
         argList = strLstNew();