Message-ID: From: "davecramer (@davecramer)" To: "pgjdbc/pgjdbc" Date: Mon, 18 May 2026 20:46:40 +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: davecramer X-GitHub-Comment-Id: 4482025094 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-4482025094 Content-Type: text/plain; charset=utf-8 Well it's not going to be possible to review this manually. So here is an AI generated review A comprehensive rewrite of the pgjdbc documentation site covering: 1. Information architecture — Flat docs split into topical sections (getting-started, connect, security, query, data-types, postgresql-features, reference, runtime, troubleshooting, migrate) 2. Release pipeline — Removes versions.toml/homepagedata.toml; homepage and download page now derive from changelog front-matter. New release = add one changelog file. 3. Compatibility page — Breakpoint-row model showing Java/PG version floors per driver line 4. CVE banners — Per-release known-CVE banners sourced from GHSA with live EPSS scores 5. Connection property reference — Generated from PGProperty annotations via ASM bytecode inspection (new :docs-tools module) 6. Homepage redesign — Hero, quick-install, release card, common-tasks grid, "Why pgJDBC" block 7. Editorial pass — Sentence case, mobile nav fix, styling discipline Architecture Highlights - :docs-tools Gradle module — ASM-based reader extracts @PgApi/@PgTags/@PgPropertyType annotations from PGProperty.class → emits connection-properties.yaml for Hugo - generateReleaseHistory — Derives release timeline from git tags - fetchKnownCves — Reads GHSA via gh api, cross-references with git tags, emits known-cves.yaml - Hugo shortcodes — param-table, code-tabs, callout, since, deprecated - Legacy URL preservation — All moved pages carry aliases: for old URLs Discussion Points (from PR comments) 1. EOL policy — The compatibility page implies a support window that hasn't been formally discussed. vlsi says it's more relaxed than SECURITY.md; davecramer wants the discussion first. 2. GitHub Pages deployment — davecramer wants to avoid manual upload to jdbc.postgresql.org. vlsi says that's orthogonal to this PR. 3. Agent-readability (llms.txt, JSON compatibility matrix, JSON Schema for connection properties) — davecramer raised it; vlsi deferred to a follow-up PR to avoid scope creep. 4. Hugo Extended required — Resolved (SCSS needs extended build; vlsi will add a build-time check). Assessment Strengths: - The single-source-of-truth principle is well-executed: one changelog file drives homepage, download page, and changelog list - The @PgApi/@PgTags/@PgPropertyType annotation system is a solid foundation for generated docs - Legacy URL preservation via aliases is thorough - The phased commit structure (0 → 0.5 → 1a → 1c → 1d) is well-organized and reviewable - Security content (authentication, Kerberos, SSL) is comprehensive and source-code-anchored Concerns: - 66 commits is a lot to review. The phased structure helps, but this is effectively a rewrite of the entire docs site. Consider whether the annotations (@PgApi etc.) should be a separate PR (vlsi already opened #4077 for that). - The :docs-tools module adds ASM 9.9.1 as a build dependency. This is build-time only and not on the runtime classpath, so it's fine, but worth noting. - EPSS overlay fetches from FIRST.org at page load. If FIRST.org is down or slow, the page still renders (graceful degradation). Good. - The gh api dependency for CVE data means CI needs GitHub CLI authenticated. The code handles missing gh gracefully (warning, no hard failure). Verdict This is an impressive, well-structured documentation overhaul. The main blocker from the discussion is the EOL policy question — the compatibility page makes claims about support windows that need maintainer consensus before publishing. Everything else is ready or close to ready. I'd suggest: 1. Resolve the EOL policy discussion (separate from this PR if needed — just placeholder the wording) 2. Split the @PgApi/@PgTags/@PgPropertyType annotations into their own PR (#4077 already exists) 3. Merge the docs restructure once the annotations PR lands and the EOL wording is agreed The technical implementation is solid. The commit messages are exceptionally detailed and the phased approach makes the 66-commit PR actually reviewable. One thing that I want to confirm is: Can this be rendered using gh-pages. Ultimately I think we want to publish this using gh-pages. Will requiring hugo-extended be a blocker ?