You are viewing a plain text version of this content. The canonical link for it is here.
Posted to pr@cassandra.apache.org by "pmcfadin (via GitHub)" <gi...@apache.org> on 2026/05/13 19:25:38 UTC
[PR] CASSANDRA-21342: Fix broken Antora xref/anchor targets in cassandra docs [cassandra]
pmcfadin opened a new pull request, #4807:
URL: https://github.com/apache/cassandra/pull/4807
This is the second PR under [CASSANDRA-21342](https://issues.apache.org/jira/browse/CASSANDRA-21342) "Fix broken Antora xref/include/image targets." The first PR ([apache/cassandra-website#319](https://github.com/apache/cassandra-website/pull/319)) covered the cassandra-website source tree (merged 2026-05-13). This PR covers the docs under `doc/modules/` in `apache/cassandra` and addresses 76+ xref errors against the website's Jenkins-build fixture.
Each commit is a single logical fix class. Per project convention they stay separate during review and squash on +1 (target: 3 final commits, one per JIRA logical group).
## Phase 3 — High-leverage cross-module patterns
These fix patterns that recur across multiple includes or branches, so one edit cascades:
- **B:** `reference:user-defined-type.adoc` / `reference:data-types.adoc` → `cassandra:developing/cql/types.adoc#{udts,native-types}`. Two partials are included by 3 CQL command pages (alter-table, create-table, create-custom-index), so one edit resolves 24 errors.
- **C:** Collections — `keyspace-check.adoc` (never existed) → `developing/cql/ddl.adoc#create-keyspace-statement`; `collection-create.adoc` xrefs missing the `/cql/` segment. 4 pages, 24 errors.
- **A2:** `master@_:ROOT:contactus.adoc` (lost in CASSANDRA-16066 Jekyll→Antora migration) → `community.adoc`. Affects `nav.adoc` and `pages/index.adoc` across 7 build branches.
Plus two reviewer-driven follow-up commits:
- A2 fix: Antora version slot `_@_` → `master@_` (cassandra-website's `antora.yml` declares `version: master`)
- C1 fix: anchor `#create-keyspace` → `#create-keyspace-statement` (explicit id wins over heading auto-id)
## Phase 4 — Trunk-lane long-tail cleanup
Targeted fixes for `apache/cassandra` trunk-only errors:
- Memtable xrefs → `storage-engine.adoc#memtables` (memtable.adoc was consolidated)
- Legacy `developing/*` paths → current `developing/cql/{ddl,types,dml}.adoc#anchor`
- Component-qualify in-page `security.adoc` anchors (two `security.adoc` files exist on trunk; unqualified xrefs are ambiguous)
- Drop duplicated `configuration/configuration/` segment in `cass_yaml_file.adoc` xrefs
- `cql_singlefile.html` → `.adoc` (Antora resolves extension at render time)
- Rewrite `commands-toc.adoc` to point at consolidated CQL anchors
- Three more broken xrefs across the two `security.adoc` pages
- `static.adoc` and `select.adoc#filtering` retargets to existing pages
- Correct paths for `monitoring.adoc` and `stcs.adoc` xrefs
- Remove dead xref to `comments-table.adoc` (kept "comments" as plain text; include directives unaffected)
## Out of scope
- **`master@_:ROOT:bugs.adoc`** in `nav.adoc:4` and `index.adoc:50` — also lost in CASSANDRA-16066. No equivalent page exists in cassandra-website. Three options (create new page, replace with external JIRA link, drop nav entry) need a `[DISCUSS]` thread before commit. Tracked separately.
- **Forward-merges to `cassandra-5.0`** for Phase 3 commits B + C (and A2 across `cassandra-5.0`, `cassandra-4.1`, `cassandra-4.0`) are committer follow-ups per the standard cherry-pick chain. `cassandra-3.11` (EOL) skipped unless reviewer requests.
## Verification
Local Antora full build (`-g`) of the cassandra-website container is impractical (≥10 min, requires Java/ant inside the container and an `accord` submodule clone; repeatedly timed out at 8 min in the ant init phase). Local minimal build (`-g`-less) can't import the cassandra component, so it can't exercise these `cassandra:` xrefs.
**Verification path is Jenkins** (the `cassandra-website` job on ci-cassandra.apache.org), same constraint PR #319 hit for its `Cassandra:` xrefs. Pre-flight structural confidence is high:
- Target file paths confirmed via grep against `upstream/trunk` working tree
- Anchor ids (`#udts`, `#native-types`, `#create-keyspace-statement`, `#memtables`) confirmed present at expected source lines
- Component-qualified prefixes match cassandra-website's `antora.yml` declarations
## AI-assistance disclosure
Per [ASF generative tooling guidance](https://www.apache.org/legal/generative-tooling.html): this PR was developed with material AI assistance. LLM-driven subagents mapped the broken-xref patterns to source files and per-branch presence on the local working tree, drafted the per-commit edits across non-overlapping scopes, and drafted the commit messages and this PR description. Commits carry a `Co-Authored-By: Claude Sonnet 4.6 <no...@anthropic.com>` trailer reflecting model attribution. All target paths, anchor ids, and prose have been reviewed by Patrick McFadin (committer), who accepts provenance and licensing responsibility per the contributor agreements. No third-party content was incorporated — every change is grounded in the existing `apache/cassandra` source tree.
## Commit-message attribution
All 15 commits currently carry `reviewed by TBD for CASSANDRA-21342`. The TBD placeholder gets amended to the reviewer's name pre-merge (same pattern as PR #319).
--
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: pr-unsubscribe@cassandra.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org
Re: [PR] CASSANDRA-21342: Fix broken Antora xref/anchor targets in cassandra docs [cassandra]
Posted by "pmcfadin (via GitHub)" <gi...@apache.org>.
pmcfadin merged PR #4807:
URL: https://github.com/apache/cassandra/pull/4807
--
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: pr-unsubscribe@cassandra.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org
Re: [PR] CASSANDRA-21342: Fix broken Antora xref/anchor targets in cassandra docs [cassandra]
Posted by "pmcfadin (via GitHub)" <gi...@apache.org>.
pmcfadin commented on PR #4807:
URL: https://github.com/apache/cassandra/pull/4807#issuecomment-4452656715
Build succeeded in CI: https://ci-cassandra.apache.org/job/cassandra-website/2771/
--
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: pr-unsubscribe@cassandra.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org