I opened https://github.com/apache/camel-website/issues/701…. now I just have to do the work :-)
David Jencks > On Nov 29, 2021, at 10:23 PM, Zoran Regvart <[email protected]> wrote: > > +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
