Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases

pgjdbc/pgjdbc GitHub issues and pull requests (mirror)  
help / color / mirror / Atom feed

From: davecramer (@davecramer) <[email protected]>
To: pgjdbc/pgjdbc <[email protected]>
Subject: Re: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases
Date: Mon, 18 May 2026 20:46:40 +0000
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>

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 ?

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