Adriano Machado created CAMEL-23531:
---------------------------------------
Summary: documentation: Jackson 3 docs in place of Jackson 2 on
dataformats
Key: CAMEL-23531
URL: https://issues.apache.org/jira/browse/CAMEL-23531
Project: Camel
Issue Type: Bug
Components: build system
Affects Versions: 4.20.0, 4.19.0
Reporter: Adriano Machado
h2. Summary
The dataformats documentation index lists Jackson 2.x and Jackson 3.x entries
under colliding basenames, so only one of each pair survives publication. As a
result, {{JSON Jackson}} on
https://camel.apache.org/components/next/dataformats/index.html resolves to a
single Jackson variant (3.x) rather than showing both 2.x and 3.x as distinct
entries.
h2. Background
While migrating the doc symlink pipeline from gulp to a Maven mojo
(CAMEL-23492), new logging surfaced 4 basename collisions in the
{{dataformats}} group. Two source files (one from {{camel-jackson}} / 2.x, one
from {{camel-jackson3}} / 3.x) flatten to the same destination filename, so the
second symlink overwrites the first.
h2. Colliding basenames
|| Basename || Source A (Jackson 2.x) || Source B (Jackson 3.x) ||
| {{jackson.adoc}} / {{jackson.json}} |
components/camel-jackson/src/main/docs/jackson-dataformat.adoc |
components/camel-jackson3/src/main/docs/jackson-dataformat.adoc |
| {{jacksonXml.adoc}} / {{jacksonXml.json}} | components/camel-jacksonxml/... |
components/camel-jacksonxml3/... |
| {{avroJackson.adoc}} / {{avroJackson.json}} |
components/camel-avro-jackson/... | components/camel-avro-jackson3/... |
| {{protobufJackson.adoc}} / {{protobufJackson.json}} |
components/camel-protobuf-jackson/... | components/camel-protobuf-jackson3/... |
Each pair collides twice — once for the {{.adoc}} page and once for the
{{.json}} metadata.
h2. Impact
* The dataformats index page lists only one of each Jackson variant.
* Users cannot discover the 2.x vs 3.x split from the public docs.
* The collision is silent — the previous gulp pipeline did not warn either; the
new mojo logs make it visible ({{linked N files (from M sources)}} where {{M >
N}}).
h2. Reproduction
# Open https://camel.apache.org/components/next/dataformats/index.html
# Search for {{JSON Jackson}} — only one entry is shown, not two.
# Check {{components/camel-jackson/src/main/docs/jackson-dataformat.adoc}} and
{{components/camel-jackson3/src/main/docs/jackson-dataformat.adoc}} — both
exist on disk but only one is published.
h2. Suggested fix
Disambiguate the destination basenames for the 3.x variants (e.g.
{{jackson3.adoc}}, {{jacksonXml3.adoc}}, {{avroJackson3.adoc}},
{{protobufJackson3.adoc}}) and update the dataformats nav so both 2.x and 3.x
entries are listed.
h2. Notes
* Discovered via the new {{PrepareDocSymlinksMojo}} logging in CAMEL-23492. The
collision pre-exists that PR; CAMEL-23492 only made it visible.
* Out of scope for CAMEL-23492 — filing separately so the doc fix has its own
review.
----
_Claude Code on behalf of Adriano Machado_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
