+1 I think this is an awesome idea, not only it helps with the maintenance it provides a nice note for end users. I like this very much.
zoran -- Sent from mobile > On 29. Nov 2021, at 20:11, David Jencks <[email protected]> wrote: > > 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
