Most or all of the camel subprojects depend on other subprojects.
For each subproject version, there are specific dependency versions. Normally,
in the documentation this will be expressed by xrefs from one component only
referring to the dependency version of the other component’s docs.
FWIW, every time I’ve looked at a subproject index page, I wonder, “what does
this depend on and at what versions?”.
I think this should be expressed clearly and visibly in the documentation, and
in a way so that it is obvious if something’s missing or if a link is to the
wrong version.
We address some of this in some antora.yml files with attributes for the
dependency versions, e.g.
```
asciidoc:
attributes:
camel-version: 3.13.x # or next? camel-quarkus next currently uses 3.13.x
camel-quarkus-version: next
camel-kamelets-version: next
```
Then xrefs can use the appropriate version with something like
xref:{camel-quarkus-version}@camel-quarkus:foo.adoc[].
I propose:
1. Expanding this consistently to all subprojects and all dependencies.
2. Having a section documenting this and a few other things prominently on each
subproject index page. What I’ve come up with so far is
rendered in preview:
```
This version ({page-component-display-version}) of camel-k depends on:
Camel
<applewebdata://162D8B74-E6E6-434E-98C3-177839B0DBD9/3.13.x@components::index.html>
at version 3.13.x
next@camel-quarkus::index.html
<applewebdata://162D8B74-E6E6-434E-98C3-177839B0DBD9/next@camel-quarkus::index.html>
at version next
next@camel-kamelets::index.html
<applewebdata://162D8B74-E6E6-434E-98C3-177839B0DBD9/next@camel-kamelets::index.html>
at version next
This is the development version of camel-k. It should not be used in production.
```
source adoc:
```
[NOTE]
--
This version ({page-component-display-version}) of camel-k depends on:
* xref:{camel-version}@components::index.adoc[Camel] at version {camel-version}
* xref:{camel-quarkus-version}@camel-quarkus::index.adoc[] at version
{camel-quarkus-version}
* xref:{camel-kamelets-version}@camel-kamelets::index.adoc[] at version
{camel-kamelets-version}
ifdef::lts[This long term service release will be supported until {lts}.]
ifndef::lts[]
ifdef::prerelease[This is the development version of camel-k. It should not be
used in production.]
ifndef::prerelease[This release will not be updated, but rather replaced by a
new release.]
endif::[]
--
```
This specific proposal involves also adding an lts attribute with the date out
of service and a prerelease boolean attribute as appropriate.
Having these explicit links will mean that, among other things, we can’t remove
a version of a component if it’s still being used by another component version,
and it will answer the most frequent question I have looking around the docs.
Thoughts?
David Jencks
