pgjdbc/pgjdbc GitHub issues and pull requests (mirror)
help / color / mirror / Atom feedFrom: vlsi (@vlsi) <[email protected]>
To: pgjdbc/pgjdbc <[email protected]>
Subject: [pgjdbc/pgjdbc] PR #4075: docs: restructure site, compatibility page, changelog-driven releases
Date: Sat, 16 May 2026 08:58:48 +0000
Message-ID: <[email protected]> (raw)
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.
<details>
<summary>Full file-level breakdown</summary>
**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
</details>
## 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
<details>
<summary>What this PR changes in detail</summary>
### 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 `<mark>`
- emitted one search-index entry per connection property so queries like `binaryTransferEnable` deep-link straight to `/documentation/reference/connection-properties/#prop-<name>`
- 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
</details>
<details>
<summary>Build the site locally</summary>
```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/
</details>
<details>
<summary>User-facing outcome</summary>
- 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
</details>
## Fixes
* https://github.com/pgjdbc/pgjdbc/issues/1687
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