Add Missing Period to HINT and DETAIL Messages
Core Problem
PostgreSQL has a documented error message style guide that mandates: "Detail and hint messages: Use complete sentences, and end each with a period." Despite this guideline existing in the official documentation, a number of errhint() and errdetail() messages throughout the codebase violate this rule by omitting trailing periods, using incorrect capitalization, or containing grammatical errors.
This is a code quality/consistency issue rather than a functional bug. The messages are user-facing strings that also feed into the translation infrastructure (via gettext/PO files), so any changes have implications for the translation workflow.
Proposed Solution
Peter Smith submitted a series of patches (evolving through v1–v5) that systematically audit and fix:
- HINT messages (patch 0001): Add missing trailing periods to
errhint()strings, fix a typo ("msut" → "must"), and update corresponding regression test expected output. - DETAIL messages (patch 0002): Add missing trailing periods to
errdetail()strings, fix capitalization issues where the first word of a detail message was lowercase.
The approach deliberately separates punctuation/formatting fixes from grammatical rewrites, keeping the scope minimal and uncontroversial.
Key Technical Design Decisions and Tradeoffs
1. Avoiding Messages Ending with Substitution Parameters
Peter Smith made a deliberate design choice to not add periods to messages where the string ends with a format specifier (e.g., %s, %d) followed by user-supplied content. The rationale: a trailing period could be visually confused as part of the substituted value (a command, filename, row value, or hex code). This is a sensible UX decision — for example:
errdetail("The failed archive command was: %s", xlogarchcmd)
Adding a period here would produce output like The failed archive command was: /usr/bin/pg_archive. where the period could be mistaken as part of the path.
2. Non-Sentences Should Not Get Periods
Peter Eisentraut (committer) raised an important refinement: the style guide says details should be sentences, and merely appending a period to a non-sentence fragment doesn't satisfy that requirement — it actually makes the output worse. The specific example:
DETAIL: syntax error at end of input.
This is a sentence fragment, not a sentence. Adding a period creates confusing output. This led to v5 of the patch removing these cases, demonstrating the principle that mechanical enforcement of one aspect of a style rule can conflict with the spirit of the rule.
3. Messages Starting with %s — Capitalization Concerns
Peter Smith raised a self-identified concern about messages like '%s depends on column \"%s\".' where the first token is a substituted value (like a rule name). The resulting output would be a "sentence" without proper capitalization:
DETAIL: rule _RETURN on view usersview depends on column "seq".
This highlights a deeper tension in PostgreSQL's error message architecture: when format strings begin with %s, the message system cannot guarantee sentence-level capitalization, making the "complete sentence with period" rule inherently difficult to enforce consistently.
4. Back-patching Policy
The thread surfaced an important process question: should these fixes be back-patched to stable branches? The consensus, anchored by Tom Lane and David Johnston:
- No back-patching for cosmetic message changes
- Changing translatable strings in back branches imposes work on translators for no functional benefit
- Only factual bugs in messages warrant back-patching
- HEAD (at this point still targeting PG19 before branch cut) is the appropriate target
Tom Lane also provided useful context about the release engineering timeline: the branch for PG19 typically happens after beta1 (late June), so HEAD-only patches at this point still land in PG19.
Scope and Coverage
The patches touched files across:
- Core backend (
src/backend/) - Contrib modules (
contrib/) — e.g.,passwordcheck - Test expected output files (
src/test/regress/expected/)
Notably, Peter Smith also identified (but did not fix) grammatical issues in partition-related messages, flagging them for potential future work:
- "can only merge partitions don't have sub-partitions" (missing "that")
- "To split DEFAULT partition one of the new partition must be DEFAULT" (multiple issues)
These were deliberately left for a separate patch to avoid scope creep and contentious rewording discussions.
Current Status
The HINT message patch (0001) was pushed by a committer (referenced by Peter Smith's "Thanks for pushing" message on 2026-04-14). The DETAIL message patch (0002) reached v5 and stalled after Peter Eisentraut's review feedback was addressed. As of the last message (2026-05-18), Peter Smith was seeking to move the DETAIL patch forward after 4 weeks of inactivity.