You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@camel.apache.org by David Jencks <da...@gmail.com> on 2021/11/29 19:11:30 UTC
Referential integrity in the website, or, keeping cross-component xrefs working and accurate.
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
Re: Referential integrity in the website, or, keeping cross-component xrefs working and accurate.
Posted by David Jencks <da...@gmail.com>.
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 <zo...@regvart.com> 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 <da...@gmail.com> 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
Re: Referential integrity in the website, or, keeping cross-component xrefs working and accurate.
Posted by Zoran Regvart <zo...@regvart.com>.
+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 <da...@gmail.com> 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