lhotari opened a new issue, #1131: URL: https://github.com/apache/pulsar-site/issues/1131
## Problem `pulsar-site` currently duplicates the entire set of `client-libraries-*` documentation pages across every versioned docs directory — `versioned_docs/version-2.2.0/` through `versioned_docs/version-4.2.x/`, 33 versions, roughly 36 client-libraries-* files per version. For most clients this is wrong. Pulsar clients are wire-compatible with older brokers for nearly all features, and the non-Java language clients have their own independent release cycles. Maintaining per-broker-version mirrors of C++/Go/Python/Node/C# docs: - Wastes maintainer effort (every client doc fix has to be applied across 30+ version dirs, often via `scripts/docs-tool.sh apply_changes_to_versioned_docs`). - Produces stale copies — older versions rarely get updates and drift from reality. - Fragments search results and confuses readers who land on a version-2.4 Python page that no longer reflects the current Python client. Only docs that are actually broker-version-coupled belong in versioned docs. ## Proposal Split `client-libraries-*` pages into two buckets. **Stay in versioned docs** (broker-version-coupled, leave as-is): - `client-libraries-java` + `client-libraries-java-setup`, `-java-initialize`, `-java-use`, `-java-tracing` — Java client ships with the broker and is the reference for wire-format/config parity. - `client-libraries-rest` — REST endpoints are broker-served and version-specific. - `client-libraries-websocket` — WebSocket proxy/protocol is broker-hosted and version-specific. **Move to a single unversioned location** at a new top-level `/client-libraries/` route (outside `/docs/`, no version segment). Implementation mirrors the existing `/contribute/` and `/release-notes/` pattern: a separate `@docusaurus/plugin-content-docs` instance in `docusaurus.config.ts` pointed at a new top-level content directory, with its own sidebar file. Pages to move: - Overview: `client-libraries` - C++: `client-libraries-cpp` (+ `-setup`, `-initialize`, `-use`) - Go: `client-libraries-go` (+ `-setup`, `-initialize`, `-use`) - Python: `client-libraries-python` (+ `-setup`, `-initialize`, `-use`) - Node.js: `client-libraries-node` (+ `-setup`, `-initialize`, `-use`, `-configs`) - C# / .NET: `client-libraries-dotnet` (+ `-setup`, `-initialize`, `-use`) Top-level rather than unversioned-under-`/docs/` is deliberate: `static/.htaccess` (line 21) unconditionally rewrites any bare `/docs/<slug>` to `/docs/4.2.x/<slug>`, so an unversioned URL *inside* `/docs/` would collide with that rule. A top-level route sidesteps the rewrite entirely. After the move: - Delete the corresponding files from every `versioned_docs/version-*/` directory and remove their entries from each `versioned_sidebars/version-*.json`. - Maintain the single canonical copy going forward. - Redirect all legacy versioned URLs to the new top-level URLs via `static/.htaccess`, e.g. `/docs/4.1.x/client-libraries-python` → `/client-libraries/python` (or whatever final slug is chosen — see open question 2). Also add equivalent entries to `@docusaurus/plugin-client-redirects` in `docusaurus.config.ts` so the redirects work in dev mode / static hosting previews where `.htaccess` is not active. ## Open questions for discussion 1. **"Advanced use" pages**: `client-libraries-clients`, `client-libraries-producers`, `client-libraries-consumers`, `client-libraries-readers`, `client-libraries-tableviews`, `client-libraries-schema`, `client-libraries-cluster-level-failover`. These are currently grouped under "Client Libraries" in `sidebars.json` but describe concepts largely through the lens of the Java client. Should they (a) move to the top-level `/client-libraries/` area alongside the non-Java clients, (b) stay versioned alongside Java, or (c) be reorganized into a language-neutral "concepts" area? Preference welcome. 2. **Slug scheme under `/client-libraries/`**: With the pages now under their own route base, the `client-libraries-` prefix in every filename/URL becomes redundant. Options: (a) keep slugs as-is so URLs look like `/client-libraries/client-libraries-python-setup` (minimizes link churn but ugly); (b) rename on move so URLs look like `/client-libraries/python-setup`, `/client-libraries/cpp`, etc. (cleaner, but requires updating internal doc links and adding extra `.htaccess` redirects). Preference welcome. 3. **Sidebar integration**: The current `sidebars.json` "Client Libraries" category (lines 322–431) groups Java/REST/WebSocket with the rest. After the split, the versioned sidebar will contain only Java + REST + WebSocket under "Client Libraries", while the new top-level `/client-libraries/` area carries the others. Should the versioned sidebar link out to the top-level pages (and vice versa) for discoverability? Also: the main navbar likely needs a "Client Libraries" entry pointing at the new top-level area. 4. **Content freshness baseline**: The top-level copy should start from the most recent versioned content (`versioned_docs/version-4.2.x/client-libraries-*` for the moved files) as the source of truth, then be maintained going forward. Confirming this is the intended baseline. ## Affected files (for whoever picks this up) - `docs/client-libraries-*.md` — remove the moved files from the current/next copy too (their canonical home becomes the new top-level directory). - New top-level directory (e.g. `client-libraries/`) — landing place for the moved files, mirroring how `contribute/` and `release-notes/` are laid out. - `versioned_docs/version-*/client-libraries-*.md` — delete moved files from all 33 versions (keep only `client-libraries-java*`, `client-libraries-rest`, `client-libraries-websocket`). - `sidebars.json` — trim the "Client Libraries" category to only the versioned-coupled pages (Java, REST, WebSocket). - `versioned_sidebars/version-*.json` — remove moved entries from all 33 files. - New sidebar file (e.g. `sidebarsClientLibraries.js`) — mirrors `sidebarsDevelopment.js` / `sidebarsReleaseNotes.js`. - `docusaurus.config.ts` — add a new `content-docs` plugin instance at `routeBasePath: "client-libraries"`; add entries to `@docusaurus/plugin-client-redirects` matching the `.htaccess` redirects. - `static/.htaccess` — add redirects from `/docs/<version>/client-libraries-<moved-slug>` (for every version, every moved slug) to the new top-level URL. No change needed to the default-version rule on line 21. ## Non-goals - Reorganizing content *within* individual client-libraries pages. - Changing the client-libraries overview page content itself. - Migrating the Java or REST/WebSocket pages. - Creating the implementation PR — this issue is for alignment on approach first. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
