First draft of PG 19 release notes

2026-05-06 · opus 4.7

Thread Overview

This thread nominally concerns Bruce Momjian's first draft of the PostgreSQL 19 release notes (212 feature entries, versus a recent average of 200), but it quickly bifurcates into two very different discussions:

Routine editorial corrections — typos, wrong author attributions, reclassifications between sections (Optimizer vs. General Performance), syntax updates reflecting post-commit renames (e.g., EXCEPT TABLE → EXCEPT (...)), and requests to add or drop particular items.
A recurring policy conflict about (a) how Co-authored-by: trailers should map to release-note attribution, and (b) whether performance improvements should be included in the release notes at all.

The second thread — especially the exchange with Andres Freund — is the substantive one. It exposes a years-long structural disagreement between Bruce's editorial philosophy and the expectations of core committers.

The Co-authored-by / Author attribution problem

Bruce applied the rule (documented on the wiki under Commit_Message_Guidance): "If no 'Author' or 'Co-authored-by' is listed, the committer is assumed to be the author." He treats Author: and Co-authored-by: as equivalent for release-note credit. Jacob Champion confirms this is the intended pattern: a missing Author: trailer means the committer is the primary author, and Co-authored-by: names everyone else.

Michael Banck questions why a bare Co-authored-by: (with no Author:) would ever make sense if the committer isn't also credited — implying the committer should always be listed as an author in that case. Bruce agrees with the logic but notes he already lost this argument in January 2025 and is unwilling to relitigate. His frustration is visible: the wiki text was quietly revised between January 2025 and March 2026, and he now operates under whatever the latest consensus was, even when it produces anomalies.

The concrete instance triggering this was Ashutosh Bapat being listed as sole author of the ShmemRequestStruct() simplification where Heikki Linnakangas (committer, no explicit Author: trailer) was the primary author. Under the current rule, Heikki was implicitly credited as author; Ashutosh's correction (to use his suggested text) resolved that particular item.

The performance-notes policy dispute (the substantive fight)

Bruce's long-standing wiki policy is:

Performance improvements are mentioned in the release notes if they are user-visible (e.g., new syntax) or significant enough to enable new workloads.

He applied this to reject David Geier's GIN build-speed improvements (measured at 1.12x–1.17x on current master because the most impactful patches in the set haven't landed), saying they'd be added once all patches are in — or not at all if they only amount to ~15%.

Andres Freund pushed back very sharply: a 12–17% index build speedup is "material" and could drive upgrade decisions. He called the policy depressing enough that he stopped reading the release notes, and provided a list of eight committers (Tom Lane, Alvaro Herrera, David Rowley, Melanie Plageman, Joe Conway, Jelte Fennema-Nio, Peter Geoghegan, Robert Haas, Noah Misch, and himself) who have raised this exact complaint in prior release cycles, going back to at least 9.5. David Rowley reinforced the point with the tidstore example: it was initially omitted from PG 17 notes and ended up being the headline feature of that release.

Bruce's defense is essentially operational rather than philosophical:

He needs rules he can mechanically apply. The performance/"new workloads" heuristic breaks down because many commits have no posted benchmark numbers, and he can't evaluate magnitude from commit messages alone.
He worries about the release notes becoming unreadable to non-hackers — his stated audience.
He argues he literally cannot describe low-level performance work in user-meaningful terms. His successful template is the optimizer section, where he can anchor entries to plan node types the reader presumably recognizes. For buffer-manager, heap-AM, or GIN internals, no analogous anchor exists.

David Rowley offered constructive procedural suggestions:

Committers should include measured numbers in commit messages (citing his own commits c456e3911 and 58a359e5 as examples) so Bruce doesn't have to trawl threads.
Fixup commits could be tagged structurally so they can be filtered out.
A WIP draft with lesser items included, pruned publicly, would shift the incentive structure — right now no one sees the items Bruce silently skips.

Andres's final concession: it's fine if Bruce doesn't want to write performance entries, but the policy shouldn't be "we don't include them." Bruce accepted this and generated a file of 1,556 excluded commits (produced with awk from the XML commit hashes), documented as step 12 on the wiki, so others can propose additions. This is a meaningful procedural shift: the process is moving from opt-in (Bruce decides what to include) to opt-out (everything is visible and the community prunes).

Technical content surfaced in corrections

Several corrections point to genuinely important PG 19 internals changes that warrant release-note mention:

Melanie Plageman's observation (probably the most consequential technical note in the thread): b46e1e54d makes SELECT queries update the visibility map — previously exclusive to vacuum. Additionally, commits d96f87332, add323da40a6bf9e0, 1252a4ee286, a759ced2f1e, and a881cc9c7e819fb eliminated XLOG_HEAP2_VISIBLE WAL records by folding VM-setting into XLOG_HEAP2_PRUNE_VACUUM_SCAN. Commit 378a21618 also sets pd_prune_xid on insert, so freshly inserted pages can now be pruned on first access and have their VM bit set without vacuum intervention. This is a significant behavioral/WAL-format change that external tools (pg_waldump consumers, logical decoding plugins, monitoring) will notice. Bruce declined to include the WAL-record detail ("too low-level") but accepted that the visible SELECT-updates-VM behavior belongs.
Nathan's autovacuum table prioritization (d7965d65f): changes the order in which autovacuum picks tables away from pg_class ordering. David Rowley flagged this as upgrade-behavioral; users who previously got good results from the implicit pg_class order may see different vacuum scheduling post-upgrade.
Jeff Davis / Andreas Karlsson's ICU UTF-8 case conversion (c4ff35f10): uses ICU's UTF8-optimized UCaseMap APIs, avoiding UTF-8↔UTF-32 round-trips on every call. Phil Florent's real-world comment is telling: ORM-generated lower(col) expression indexes are ubiquitous on UTF-8 databases, so this is precisely the kind of "invisible" performance change that affects every deployed ORM workload. This is a strong example of Andres's point — it has no user-visible syntax change, but it's exactly the sort of thing that drives upgrades.
Richard Guo's JSON_ARRAY(subquery) fix (8d829f5a0): a late-breaking behavioral change for SQL/JSON conformance — empty subquery now returns '[]'::json instead of NULL. This is a migration-section item because application code may break.
WITHOUT OVERLAPS + domains (Tom Lane, 4edd6036d): backpatched to 18, so correctly excluded from 19 notes. Bruce's catch here shows the mechanical scan he does: backpatch-through tag gates inclusion.
COPY TO on partitioned tables (ecd9288624): a genuine new capability Bruce had missed; he added it.

Whose opinions carry weight

Andres Freund (committer, storage/executor/infrastructure expert): his intervention effectively forces the process change. His list of eight senior committers objecting across releases is the rhetorical sledgehammer that made Bruce concede a structural change rather than another one-off exception.
David Rowley (committer, executor/planner): provides the constructive middle path — tooling and commit-message discipline rather than policy fights. His tidstore anecdote from PG 17 is the most persuasive single data point in the thread.
Melanie Plageman (committer, vacuum/heap AM): her VM/WAL observations are the kind of nuanced internals input only the original author can provide; they illustrate why Bruce cannot realistically curate this himself.
Bruce Momjian: the release-notes editor for many releases. His stance is defensive-operational rather than ideological — he isn't opposed to listing performance work, he just cannot personally produce good text for it without domain help.
Jacob Champion, Michael Banck, Ashutosh Bapat: contributors to the attribution sub-discussion, mostly asking for clearer rules.

Design tradeoffs

The thread exposes a genuine unresolved tension:

Audience model: Bruce writes for "general Postgres users" who will be overwhelmed by detail. Andres writes for DBAs and application owners who need to decide whether an upgrade solves their problem. Both audiences are legitimate; the release notes currently only serve the first.
Labor allocation: curating 212 entries is already a heavy job. Doubling it to include every non-trivial performance commit is not feasible for one person. But requiring committers to include benchmark numbers and explicit "please mention" flags distributes the load.
Discoverability vs. noise: Rowley's suggestion of per-entry icons (feature / perf / behavioral change) would let readers filter without forcing Bruce to shrink the list.