pgjdbc/pgjdbc GitHub issues and pull requests (mirror)
help / color / mirror / Atom feedFrom: sehrope (@sehrope) <[email protected]>
To: pgjdbc/pgjdbc <[email protected]>
Subject: Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases
Date: Wed, 20 May 2026 11:18:44 +0000
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
> AI-generated prose / em-dashes. I don't have an action item I can take from this part of the review. Em-dashes are standard English typography (Chicago, AP, NYT, The Economist all use them in the role they have here — parenthetical clauses, appositives, definition setups). "Fewer em-dashes" doesn't decompose into specific edits I can make.
This is technical documentation. Not a a newspaper. We didn't have them before, and we should not be introducing them now. There's also technical reasons to stick with printable ASCII characters for source and in documentation. There's even stronger technical reasons not to have them in git commit messages.
The wider problem with the AI generated documentation is that nobody is reading it or you're expecting somebody else to do so.
> If there are pages with factual errors or passages that read awkwardly, point at them and I'll fix what's named. I have checked the contents, and it looks reasonable to me. I'm not going to search-and-replace correct typography.
Did you read every single line of the AI generated documentation to verify it for correctness before asking others to do that?
> Custom Kotlin/Gradle code. "Too complicated" is hard to act on without a concrete alternative.
There's always the concrete alternative of simply not doing it.
Just because some code automates some manual task does not mean we want it in the repo. There's a future maintenance to keep in mind as well and we would do well to limit that maintenance surface.
I don't even think changelogs should be automated. Nobody cares about reading automated commit message changelogs. People want meaningful features, fixes, and breaking behavior. As much as we try to make that possible via commit message formatting, it's not 100%, so there's always a manual step anyway.
I do not think the manual process is particularly onerous. I think the real problem is that with all the plugins and GHA changes recently, we had no clue how the hell the whole thing worked. Once that's been locked down and consistent, having a simple checklist to ensure the changelog has been updated is more than enough. We don't need even more code in the repo for this type of thing.
> What I'm not going to do is rebuild all 78 commits into atomic "each one builds and passes tests" units. That's many days of interactive rebase on a tangled history for marginal benefit, given most commits are already self-contained. If you want specific stretches squashed, name them and I'll do those.
If you do not do it, you're expecting others to either to do it for you as part of their review or simply not read anything. The PR submitter is responsible for formatting things in a way that represents logical change sets. 70+ commits that each change one or two files with four paragraphs of AI slop commit messages is not fit for human consumption.
I'm saying if you really care about someone else actually taking the time to give this a meaningful review then you need to structure it such that it's actually possible to do so. Not just a 14000+ line diff.
view thread (64+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: github://pgjdbc/pgjdbc
Cc: [email protected], [email protected]
Subject: Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases
In-Reply-To: <<[email protected]>>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox