Message-ID: From: "vlsi (@vlsi)" To: "pgjdbc/pgjdbc" Date: Tue, 19 May 2026 16:08:18 +0000 Subject: Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases In-Reply-To: References: List-Id: X-GitHub-Author-Login: vlsi X-GitHub-Comment-Id: 4489685764 X-GitHub-Comment-Type: issue_comment X-GitHub-Issue: 4075 X-GitHub-Repo: pgjdbc/pgjdbc X-GitHub-Type: comment X-GitHub-Url: https://github.com/pgjdbc/pgjdbc/pull/4075#issuecomment-4489685764 Content-Type: text/plain; charset=utf-8 **Support policy / JDK 6/7 / 5-year window**. Agreed these need offline discussion before they land anywhere — extracted to [#4079](https://github.com/pgjdbc/pgjdbc/pull/4079), let's iterate there. Nothing about JDK 6/7 deprecation or the five-year window will land here without sign-off in that thread. **Annotations (@PgApi, @PgTags, @PgPropertyType)**. Already its own PR — [#4077](https://github.com/pgjdbc/pgjdbc/pull/4077). Please drop annotation-specific comments there. **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. 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. **Custom Kotlin/Gradle code**. "Too complicated" is hard to act on without a concrete alternative. Options I considered and rejected: * Hand-maintained known-cves.yaml. Hand-syncing with GHSA is unreliable. It would make release more complicated. https://github.com/pgjdbc/pgjdbc/pull/4078 is a proof we already have issues with hand-maintained files in our documentaiton. * Java instead of Kotlin. It does not make the code smaller, and it adds NPE issues, and it slows down the compilation. Checkerframework verification for Java is slow. LLMS and humans are not proficient with `@Nullable`. If you see another path that drops complexity without dropping functionality, name it. Otherwise the unit of review here is "does the generator produce correct output", and the JUnit tests under docs-tools/src/test/kotlin/ cover that. Splitting the tooling into a standalone PR doesn't work either — it has no visible effect without the templates that consume the YAML it generates. Splitting would produce one PR that generates output nobody reads, and another PR that references output that doesn't exist. **Squash / commit count**. Yes, 78 is a lot. But the natural unit of review here is one commit = one page rewrite. Phase 1c — security/authentication.md is a self-contained reviewable chunk. Squashing into ~10 chunks would mean each chunk covers 7+ pages, and the per-page boundaries vanish in a combined diff — that makes review harder, not easier. 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. **Generation vs verbiage**. The principle is right — refactor with byte-identical output first, then change output — but it isn't retroactively recoverable here without redoing the work. What I can do is annotate the PR description with the structure: which commits are tooling-only (output byte-identical), which add data fields, which change presentation, which rewrite prose. That gives you a reading map without a re-split.