[
https://issues.apache.org/jira/browse/CAMEL-23531?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-23531:
--------------------------------
Issue Type: Task (was: Bug)
> documentation: Jackson 3 collides with Jackson 2 on dataformats docs
> --------------------------------------------------------------------
>
> Key: CAMEL-23531
> URL: https://issues.apache.org/jira/browse/CAMEL-23531
> Project: Camel
> Issue Type: Task
> Components: build system
> Affects Versions: 4.19.0, 4.20.0
> Reporter: Adriano Machado
> Assignee: Adriano Machado
> Priority: Major
>
> 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)
