Message-ID: From: "vlsi (@vlsi)" To: "pgjdbc/pgjdbc" Date: Sat, 16 May 2026 08:58:48 +0000 Subject: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases List-Id: X-GitHub-Author-Id: 213894 X-GitHub-Author-Login: vlsi X-GitHub-Issue: 4075 X-GitHub-Labels: documentation X-GitHub-Repo: pgjdbc/pgjdbc X-GitHub-State: closed X-GitHub-Type: pull_request X-GitHub-Url: https://github.com/pgjdbc/pgjdbc/pull/4075 Content-Type: text/plain; charset=utf-8 Documentation rework: new information architecture, sentence-case styling, compatibility page, and a release pipeline driven entirely by changelog front matter. Ready for review. The change looks good to me: I would approve a PR of this shape if it came from another contributor. ## What and why The documentation had grown around a flat, historically-shaped set of pages. Important topics like connection setup, SSL/TLS, prepared statements, PostgreSQL extensions, and compatibility guidance were either buried in oversized pages or hard to discover from navigation. The release-presentation side had a parallel problem: home page, download page, and per-version notices were each driven by their own hand-maintained config files, so cutting a release meant editing several files in lockstep. This PR reorganises content into task-oriented sections, splits oversized pages, adds a compatibility page, and unifies the release pipeline. Cutting a regular release is now one changelog file. Nothing else. **Preview:** https://vlsi.github.io/pgjdbc/ ## Diff at a glance 13.8k insertions / 3.0k deletions across 264 files. Most of it is not prose: | Category | Added | What it is | |---|---:|---| | Prose to read | ~5.6k | 40 narrative pages in `docs/content/` | | Doc-tools code | ~3.6k | Kotlin generators, tests, and Gradle | | Site infrastructure | ~3.9k | Hugo templates, SCSS, JS (lunr search, code tabs, EPSS overlay) | | Seed data | ~0.4k | release-history overlay, changelog front-matter | The **review-heavy** portion is **~5.6k lines of prose** across ~40 pages. Everything else is exercised by tests, the build, and the preview rather than by reading line by line.
Full file-level breakdown **Prose (5,869):** - Non-changelog narrative: 5,645 lines in 63 files (~40 real pages; the remainder are `_index.md` stubs and rename-duplicates in numstat) - Changelog front-matter: 224 lines, one `description:` line each (read-once seed data) **Doc-tools (~3,600):** - `docs-tools/src/main/kotlin/`: 1,496 (ClassFileReader, FetchKnownCves, GenerateReleaseHistory, GenerateProperties, ReflectionEnricher, Validator, YamlEmitter, PropertyRecord) - `docs-tools/build.gradle.kts`: 493 - `docs-tools/src/test/kotlin/`: 926 - pgjdbc-side: `PgApi`, `PgTags`, `PgPropertyType`, `package-info` (412), and `PGProperty.java` (+267) **Test fixtures (~360):** - `release-history-overlay.yaml`: 135 (curated overlay for GenerateReleaseHistory) - changelog front-matter: 224 (read-once description seed) - `versions.toml` removed (-119), `homepagedata.toml` net -29 **Site infrastructure (~3,940):** - `docs/layouts/` (Hugo templates, shortcodes, partials): 1,438 - `docs/assets/sass/` (SCSS): 1,518 - `docs/static/` (JS: lunr-search, search-highlight, code-tabs, known-cves-epss, param-table, legacy-anchors, plus images): 874 - `docs/config/`, `.github/workflows/docs.yml`, `docs/.gitignore`: 112
## Reviewing this PR If 13.8k lines look intimidating, see the breakdown above. About 5.6k is prose across 40 pages; the rest is code, templates, and styles verified by the build and tests. **Quick contribution (~15 minutes):** pick any one page from https://vlsi.github.io/pgjdbc/documentation/, read it, and drop a comment on this PR with anything that reads wrong: technical mistakes, awkward phrasing, broken or missing links, confusing structure. You do not need deep JDBC context for prose feedback; native-speaker reads are especially welcome. **Deeper review:** the focus areas below outline the architecturally interesting changes. ## Suggested focus areas * top-level documentation section split * sidebar and navigation flow * legacy URL preservation for moved pages * compatibility page structure and terminology * CVE / EPSS banner content on changelog pages * troubleshooting pages
What this PR changes in detail ### Information architecture - homepage redesign and CTA cleanup - split large legacy documentation pages into smaller topical pages - reorganised `docs/content/documentation/` into task-oriented sections such as: - `getting-started` - `connect` - `security` - `query` - `data-types` - `postgresql-features` - `reference` - `runtime` - `troubleshooting` - `migrate` - added section landing pages - replaced the flat docs menu with a two-level sidebar driven by the content tree - preserved legacy URLs via aliases and hub pages for moved or split content - separated PostgreSQL-specific driver extensions from generic JDBC topics - added a compatibility page modelled as breakpoint rows rather than one row per release - added a troubleshooting section with pages for the most common real-world failure shapes - kept the connection-property reference generated from code metadata rather than hand-maintained prose ### Release and changelog pipeline - removed `versions.toml`, `homepagedata.toml`, and the per-release config files entirely - homepage release card, download page, and changelog list all derive from the front matter of the changelog pages themselves - cutting a regular release is now: add one `changelog.md` file. Nothing else. - changelog list rendered as version, date, and summary rows - added a per-release known-CVE banner sourced from GHSA, with a live EPSS overlay for "affected" and "fixed" CVEs - relocated the standing Log4Shell notice to `/security/` so it stops crowding the homepage ### Editorial and style pass - unified page titles to sentence case, dropped numbered section prefixes - discipline pass on the site-wide blue, killed a blanket `p` rule; mobile nav no longer occludes the page footer - quick-install block stacks Maven and Gradle (instead of a three-tab widget) with a copy-to-clipboard button that works in non-secure contexts - hero, "Why pgJDBC", "Common tasks", and closing blocks replaced with hand-written components rather than the old generic homepage partials - fixed Hugo deprecations - fixed three changelog date and filename discrepancies discovered during the front-matter conversion ### Site search - replaced the previous search (a form that posted to a separate results page) with a live dropdown that opens under the field as the user types - bound `/` as a global focus shortcut; arrow keys navigate the result list, Enter follows the active result, Esc and outside-click close it - snippets are now relevance fragments extracted around each match (via lunr `matchData` positions), not a slice truncated at the first paragraph; matched terms are wrapped in `` - emitted one search-index entry per connection property so queries like `binaryTransferEnable` deep-link straight to `/documentation/reference/connection-properties/#prop-` - custom lunr tokeniser splits camelCase, PascalCase, `ACRONYMWord`, and snake_case across **all** fields and documents; adjacent-component bigrams cover concatenated substrings, so `fetchsize`, `rowfetch`, `channel_binding`, and `ChannelBinding` all surface the same property
Build the site locally ```bash ./gradlew --quiet serveDocs ``` Then open: * http://localhost:1313/ * documentation index: http://localhost:1313/documentation/ * compatibility page: http://localhost:1313/documentation/getting-started/compatibility/ * changelogs (any version, to see the CVE banner): http://localhost:1313/changelogs/
User-facing outcome - clearer homepage that answers typical users' questions - new users have a coherent path through `getting-started/` - connection and security topics are easier to find from navigation - PostgreSQL-specific functionality is no longer buried under generic query and API pages - compatibility guidance is easier to discover and reason about - each release page now surfaces known CVEs and their current EPSS scores - older inbound links continue to work after the restructuring - searching for a connection property by any spelling (`fetchsize`, `RowFetch`, `channel_binding`) jumps straight to the property in the reference table
## Fixes * https://github.com/pgjdbc/pgjdbc/issues/1687