diff --git a/CODING.md b/CODING.md index 1b883237b..12f72abb1 100644 --- a/CODING.md +++ b/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 diff --git a/doc/xml/coding.xml b/doc/xml/coding.xml index 621a29a5d..d39b4498d 100644 --- a/doc/xml/coding.xml +++ b/doc/xml/coding.xml @@ -162,6 +162,14 @@ 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.

+
diff --git a/lib/pgBackRest/Archive/Info.pm b/lib/pgBackRest/Archive/Info.pm index b5dbf6bb0..447185cce 100644 --- a/lib/pgBackRest/Archive/Info.pm +++ b/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 diff --git a/lib/pgBackRest/Backup/Info.pm b/lib/pgBackRest/Backup/Info.pm index 289e7e1b3..1edb21de1 100644 --- a/lib/pgBackRest/Backup/Info.pm +++ b/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 { diff --git a/lib/pgBackRest/Common/Ini.pm b/lib/pgBackRest/Common/Ini.pm index dd3dd6100..697ef9c0a 100644 --- a/lib/pgBackRest/Common/Ini.pm +++ b/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}); diff --git a/lib/pgBackRest/Db.pm b/lib/pgBackRest/Db.pm index 11bd2d023..83c7e7a8f 100644 --- a/lib/pgBackRest/Db.pm +++ b/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); } diff --git a/src/command/archive/common.c b/src/command/archive/common.c index 30bfefb0e..3ed8059c3 100644 --- a/src/command/archive/common.c +++ b/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)); } diff --git a/src/command/check/check.c b/src/command/check/check.c index 903eb09e8..79c124abc 100644 --- a/src/command/check/check.c +++ b/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 PostgreSQL server log for errors.", + "HINT: check the archive_command to ensure that all options are correct (especially --stanza).\n" + "HINT: check the PostgreSQL server log for errors.", strPtr(walSegment), archiveTimeout); } } diff --git a/src/command/check/common.c b/src/command/check/common.c index 219a624c0..695c21a78 100644 --- a/src/command/check/common.c +++ b/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))); } diff --git a/src/command/info/info.c b/src/command/info/info.c index 03e05cf03..c993f9c81 100644 --- a/src/command/info/info.c +++ b/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(); diff --git a/src/config/load.c b/src/config/load.c index 616d53e0c..48cc341ea 100644 --- a/src/config/load.c +++ b/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: TLS/SSL verification cannot proceed with this bucket name" - "\nHINT: remove dots from the bucket name", + "\nHINT: RFC-2818 forbids dots in wildcard matches." + "\nHINT: TLS/SSL verification cannot proceed with this bucket name." + "\nHINT: remove dots from the bucket name.", strPtr(cfgOptionStr(cfgOptRepoS3Bucket))); } diff --git a/src/perl/embed.auto.c b/src/perl/embed.auto.c index d951a4488..35f312de2 100644 --- a/src/perl/embed.auto.c +++ b/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" diff --git a/test/lib/pgBackRestTest/Module/Common/CommonIniPerlTest.pm b/test/lib/pgBackRestTest/Module/Common/CommonIniPerlTest.pm index 8b0471577..c2e1e1b68 100644 --- a/test/lib/pgBackRestTest/Module/Common/CommonIniPerlTest.pm +++ b/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?"); } ################################################################################################################################ diff --git a/test/lib/pgBackRestTest/Module/Info/InfoInfoArchivePerlTest.pm b/test/lib/pgBackRestTest/Module/Info/InfoInfoArchivePerlTest.pm index d44fb996d..e6dd072b8 100644 --- a/test/lib/pgBackRestTest/Module/Info/InfoInfoArchivePerlTest.pm +++ b/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} . '*'); diff --git a/test/lib/pgBackRestTest/Module/Info/InfoInfoBackupPerlTest.pm b/test/lib/pgBackRestTest/Module/Info/InfoInfoBackupPerlTest.pm index 7bfa35156..d027b5c59 100644 --- a/test/lib/pgBackRestTest/Module/Info/InfoInfoBackupPerlTest.pm +++ b/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?"); } } diff --git a/test/src/module/command/archiveCommonTest.c b/test/src/module/command/archiveCommonTest.c index f5fce9567..9a4c6c6dc 100644 --- a/test/src/module/command/archiveCommonTest.c +++ b/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."); } diff --git a/test/src/module/command/archivePushTest.c b/test/src/module/command/archivePushTest.c index 66bd031bd..0cc1f9dea 100644 --- a/test/src/module/command/archivePushTest.c +++ b/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 diff --git a/test/src/module/command/checkTest.c b/test/src/module/command/checkTest.c index 18378bf0f..272eba363 100644 --- a/test/src/module/command/checkTest.c +++ b/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 PostgreSQL server log for errors."); + "HINT: check the archive_command to ensure that all options are correct (especially --stanza).\n" + "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)); } diff --git a/test/src/module/command/infoTest.c b/test/src/module/command/infoTest.c index 0dcc0063b..461112ca8 100644 --- a/test/src/module/command/infoTest.c +++ b/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)))); } diff --git a/test/src/module/command/stanzaTest.c b/test/src/module/command/stanzaTest.c index dc317055f..a2b13d7bf 100644 --- a/test/src/module/command/stanzaTest.c +++ b/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)); diff --git a/test/src/module/config/loadTest.c b/test/src/module/config/loadTest.c index 66b55a5aa..f5e9fa76e 100644 --- a/test/src/module/config/loadTest.c +++ b/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: TLS/SSL verification cannot proceed with this bucket name" - "\nHINT: remove dots from the bucket name"); + "\nHINT: RFC-2818 forbids dots in wildcard matches." + "\nHINT: TLS/SSL verification cannot proceed with this bucket name." + "\nHINT: remove dots from the bucket name."); // Invalid bucket name with verification disabled succeeds argList = strLstNew();