You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2021/12/03 11:35:03 UTC
[camel] branch main updated: Update doc instructions, including website release instructions (#6497)
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 08e6572 Update doc instructions, including website release instructions (#6497)
08e6572 is described below
commit 08e657294327cbe2b06d8d87c4cbb474a3daf33b
Author: djencks <dj...@apache.org>
AuthorDate: Fri Dec 3 03:33:56 2021 -0800
Update doc instructions, including website release instructions (#6497)
* non-archaic user manual images location
* Improve website release guide and doc guides
---
.../images/books/3151EN_Mastering_Apache_Camel.jpg | Bin
.../ROOT/{assets => }/images/books/3477OS.jpg | Bin
.../ROOT/{assets => }/images/books/3477OSmall.jpg | Bin
.../ROOT/{assets => }/images/books/5347OSmall.jpg | Bin
.../images/books/B03507_MockupCover_Normal.jpg | Bin
.../images/books/CamelCookbookCover.png | Bin
.../{assets => }/images/books/CiA-front-medium.png | Bin
.../images/books/camel-design-patterns.jpg | Bin
.../{assets => }/images/books/cia2-cover-small.jpg | Bin
.../ROOT/{assets => }/images/books/cia_small.jpg | Bin
.../{assets => }/images/books/eip_book_cover.jpg | Bin
.../ROOT/{assets => }/images/books/large.jpg | Bin
.../ROOT/{assets => }/images/books/rademakers.jpg | Bin
.../images/images/EventDrivenConsumerSolution.gif | Bin
.../images/images/MessageEndpointSolution.gif | Bin
.../images/images/MessageTranslator.gif | Bin
.../apache-spark.data/camel_spark_cluster.png | Bin
.../apache-spark.data/camel_spark_driver.png | Bin
.../images/apache-spark.data/fabric_docker-(2).png | Bin
.../images/barcode-data-format.data/qr-code.png | Bin
.../images/images/camel-architecture.png | Bin
.../{assets => }/images/images/camel-context.png | Bin
.../ROOT/{assets => }/images/images/camel-logo.png | Bin
.../ROOT/{assets => }/images/images/debug.png | Bin
.../images/direct-vm.data/camel-direct-vm.png | Bin
.../download.data/camel-box-v1.0-150x200.png | Bin
.../images/images/endpoint-factory.png | Bin
.../images/images/endpoint-uri-syntax.png | Bin
.../enterprise-integration-patterns.data/clear.png | Bin
.../images/images/message_flow_in_route.png | Bin
.../images/images/service_lifecycle.png | Bin
docs/user-manual/modules/ROOT/nav.adoc | 1 +
.../ROOT/pages/improving-the-documentation.adoc | 39 ++---
.../modules/ROOT/pages/release-guide-website.adoc | 190 +++++++++------------
.../modules/ROOT/pages/release-guide.adoc | 1 +
.../flow.png | Bin 6152 -> 0 bytes
.../message-flow-in-route.png | Bin 13415 -> 0 bytes
.../flow.png | Bin
.../message-flow-in-route.png | Bin
.../faq/pages/how-does-the-website-work.adoc | 2 +-
40 files changed, 103 insertions(+), 130 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/3151EN_Mastering_Apache_Camel.jpg b/docs/user-manual/modules/ROOT/images/books/3151EN_Mastering_Apache_Camel.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/3151EN_Mastering_Apache_Camel.jpg
rename to docs/user-manual/modules/ROOT/images/books/3151EN_Mastering_Apache_Camel.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/3477OS.jpg b/docs/user-manual/modules/ROOT/images/books/3477OS.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/3477OS.jpg
rename to docs/user-manual/modules/ROOT/images/books/3477OS.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/3477OSmall.jpg b/docs/user-manual/modules/ROOT/images/books/3477OSmall.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/3477OSmall.jpg
rename to docs/user-manual/modules/ROOT/images/books/3477OSmall.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/5347OSmall.jpg b/docs/user-manual/modules/ROOT/images/books/5347OSmall.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/5347OSmall.jpg
rename to docs/user-manual/modules/ROOT/images/books/5347OSmall.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/B03507_MockupCover_Normal.jpg b/docs/user-manual/modules/ROOT/images/books/B03507_MockupCover_Normal.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/B03507_MockupCover_Normal.jpg
rename to docs/user-manual/modules/ROOT/images/books/B03507_MockupCover_Normal.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/CamelCookbookCover.png b/docs/user-manual/modules/ROOT/images/books/CamelCookbookCover.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/CamelCookbookCover.png
rename to docs/user-manual/modules/ROOT/images/books/CamelCookbookCover.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/CiA-front-medium.png b/docs/user-manual/modules/ROOT/images/books/CiA-front-medium.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/CiA-front-medium.png
rename to docs/user-manual/modules/ROOT/images/books/CiA-front-medium.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/camel-design-patterns.jpg b/docs/user-manual/modules/ROOT/images/books/camel-design-patterns.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/camel-design-patterns.jpg
rename to docs/user-manual/modules/ROOT/images/books/camel-design-patterns.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/cia2-cover-small.jpg b/docs/user-manual/modules/ROOT/images/books/cia2-cover-small.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/cia2-cover-small.jpg
rename to docs/user-manual/modules/ROOT/images/books/cia2-cover-small.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/cia_small.jpg b/docs/user-manual/modules/ROOT/images/books/cia_small.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/cia_small.jpg
rename to docs/user-manual/modules/ROOT/images/books/cia_small.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/eip_book_cover.jpg b/docs/user-manual/modules/ROOT/images/books/eip_book_cover.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/eip_book_cover.jpg
rename to docs/user-manual/modules/ROOT/images/books/eip_book_cover.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/large.jpg b/docs/user-manual/modules/ROOT/images/books/large.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/large.jpg
rename to docs/user-manual/modules/ROOT/images/books/large.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/books/rademakers.jpg b/docs/user-manual/modules/ROOT/images/books/rademakers.jpg
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/books/rademakers.jpg
rename to docs/user-manual/modules/ROOT/images/books/rademakers.jpg
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/EventDrivenConsumerSolution.gif b/docs/user-manual/modules/ROOT/images/images/EventDrivenConsumerSolution.gif
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/EventDrivenConsumerSolution.gif
rename to docs/user-manual/modules/ROOT/images/images/EventDrivenConsumerSolution.gif
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/MessageEndpointSolution.gif b/docs/user-manual/modules/ROOT/images/images/MessageEndpointSolution.gif
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/MessageEndpointSolution.gif
rename to docs/user-manual/modules/ROOT/images/images/MessageEndpointSolution.gif
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/MessageTranslator.gif b/docs/user-manual/modules/ROOT/images/images/MessageTranslator.gif
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/MessageTranslator.gif
rename to docs/user-manual/modules/ROOT/images/images/MessageTranslator.gif
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/apache-spark.data/camel_spark_cluster.png b/docs/user-manual/modules/ROOT/images/images/apache-spark.data/camel_spark_cluster.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/apache-spark.data/camel_spark_cluster.png
rename to docs/user-manual/modules/ROOT/images/images/apache-spark.data/camel_spark_cluster.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/apache-spark.data/camel_spark_driver.png b/docs/user-manual/modules/ROOT/images/images/apache-spark.data/camel_spark_driver.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/apache-spark.data/camel_spark_driver.png
rename to docs/user-manual/modules/ROOT/images/images/apache-spark.data/camel_spark_driver.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/apache-spark.data/fabric_docker-(2).png b/docs/user-manual/modules/ROOT/images/images/apache-spark.data/fabric_docker-(2).png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/apache-spark.data/fabric_docker-(2).png
rename to docs/user-manual/modules/ROOT/images/images/apache-spark.data/fabric_docker-(2).png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/barcode-data-format.data/qr-code.png b/docs/user-manual/modules/ROOT/images/images/barcode-data-format.data/qr-code.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/barcode-data-format.data/qr-code.png
rename to docs/user-manual/modules/ROOT/images/images/barcode-data-format.data/qr-code.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/camel-architecture.png b/docs/user-manual/modules/ROOT/images/images/camel-architecture.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/camel-architecture.png
rename to docs/user-manual/modules/ROOT/images/images/camel-architecture.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/camel-context.png b/docs/user-manual/modules/ROOT/images/images/camel-context.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/camel-context.png
rename to docs/user-manual/modules/ROOT/images/images/camel-context.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/camel-logo.png b/docs/user-manual/modules/ROOT/images/images/camel-logo.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/camel-logo.png
rename to docs/user-manual/modules/ROOT/images/images/camel-logo.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/debug.png b/docs/user-manual/modules/ROOT/images/images/debug.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/debug.png
rename to docs/user-manual/modules/ROOT/images/images/debug.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/direct-vm.data/camel-direct-vm.png b/docs/user-manual/modules/ROOT/images/images/direct-vm.data/camel-direct-vm.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/direct-vm.data/camel-direct-vm.png
rename to docs/user-manual/modules/ROOT/images/images/direct-vm.data/camel-direct-vm.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/download.data/camel-box-v1.0-150x200.png b/docs/user-manual/modules/ROOT/images/images/download.data/camel-box-v1.0-150x200.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/download.data/camel-box-v1.0-150x200.png
rename to docs/user-manual/modules/ROOT/images/images/download.data/camel-box-v1.0-150x200.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/endpoint-factory.png b/docs/user-manual/modules/ROOT/images/images/endpoint-factory.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/endpoint-factory.png
rename to docs/user-manual/modules/ROOT/images/images/endpoint-factory.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/endpoint-uri-syntax.png b/docs/user-manual/modules/ROOT/images/images/endpoint-uri-syntax.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/endpoint-uri-syntax.png
rename to docs/user-manual/modules/ROOT/images/images/endpoint-uri-syntax.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/enterprise-integration-patterns.data/clear.png b/docs/user-manual/modules/ROOT/images/images/enterprise-integration-patterns.data/clear.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/enterprise-integration-patterns.data/clear.png
rename to docs/user-manual/modules/ROOT/images/images/enterprise-integration-patterns.data/clear.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/message_flow_in_route.png b/docs/user-manual/modules/ROOT/images/images/message_flow_in_route.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/message_flow_in_route.png
rename to docs/user-manual/modules/ROOT/images/images/message_flow_in_route.png
diff --git a/docs/user-manual/modules/ROOT/assets/images/images/service_lifecycle.png b/docs/user-manual/modules/ROOT/images/images/service_lifecycle.png
similarity index 100%
rename from docs/user-manual/modules/ROOT/assets/images/images/service_lifecycle.png
rename to docs/user-manual/modules/ROOT/images/images/service_lifecycle.png
diff --git a/docs/user-manual/modules/ROOT/nav.adoc b/docs/user-manual/modules/ROOT/nav.adoc
index 68090ff..0c9e227 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -22,6 +22,7 @@
** xref:rest-dsl.adoc[Working with REST and Rest DSL]
** xref:writing-components.adoc[Writing Components]
** xref:release-guide.adoc[Release guide]
+*** xref:release-guide-website.adoc[Adding doc versions to the website]
** xref:improving-the-documentation.adoc[Improving the Documentation]
* xref:migration-and-upgrade.adoc[Migration and Upgrade]
** xref:camel-3-migration-guide.adoc[Camel 2.x to 3.0 Migration Guide]
diff --git a/docs/user-manual/modules/ROOT/pages/improving-the-documentation.adoc b/docs/user-manual/modules/ROOT/pages/improving-the-documentation.adoc
index 44aaddd..223b3db 100644
--- a/docs/user-manual/modules/ROOT/pages/improving-the-documentation.adoc
+++ b/docs/user-manual/modules/ROOT/pages/improving-the-documentation.adoc
@@ -6,11 +6,17 @@ a tiny typo fix, or adding more details to an existing component, etc.
NOTE: This page only describes working with the 'documentation' portion of the website.
Other portions are written in markdown and built using Hugo.
+== Simple changes
+
+If there's an `edit this page` button at the top right of the page and you wish to propose a simple change such as fixing a typo or rewording something, use this xref:faq:how-do-i-edit-the-website.adoc[very simple process].
+For more complicated changes, including changing xrefs, adding, removing or renaming pages, and significant organizational changes, please use the process described on this page.
+
== Where to find the documentation
All of the documentation accessible in the left-hand navigation panel in the documentation portion of the website is managed in the link:https://asciidoc.org/[AsciiDoc format] and built with the https://antora.org[Antora] static site generator.
-As of November 2021, by far the most capable Asciidoc editor is the Intellij Asciidoc plugin, which works with all Intellij editor projects including the free Community Edition.
+As of November 2021, by far the most capable Asciidoc editor is the Intellij Asciidoc plugin, which works with all Intellij editor products including the free IDEA Community Edition.
The plugin preview is more capable than viewing a local Asciidoc file with a browser plugin as it has some understanding of Antora structure.
+Note that the only reliable way to preview your changes is with a full build of the Antora portion of the website.
The files have the extension `.adoc` and are managed in the Camel repositories.
General documentation is usually directly editable.
@@ -50,7 +56,7 @@ Please do not use this method if you are changing any xrefs or making significan
. Create a branch for your work with a name starting with the original branch name, e.g. `git switch -c main-doc-fix`
. Edit the `.adoc` sources as needed.
Preview your work in the Intellij Asciidoc plugin preview or in a browser with an Asciidoctor extension installed.
-. Do a xref:#_how_to_build_the_website_locally_with_your_changes[local website build with your changes].
+. Do a xref:#_local_build_instructions[local website build with your changes].
//=== The following workflow may be usable after https://gitlab.com/antora/antora/-/issues/831 is implemented, perhaps with the aid of an Antora extension.
//. Commit and push your work and create a PR in the (sub)project repository.
//Note the PR number, e.g. #456
@@ -85,6 +91,7 @@ There will be an email with the preview URL.
. Upon approval, your content PR will be merged.
Unless you have made a considerably more extensive change than described above, the `camel-website` PR will not need to be merged and may be closed.
+[#_local_build_instructions]
== How to build the website locally, with your changes
First, make sure you have yarn, version >= 3.1.0, installed globally.
@@ -116,7 +123,7 @@ yarn build-all
=== Adjusting the playbook to include local changes
-The Antora build is specified in the `camel-website/antora-playbook.yml` playbook.
+The Antora build is specified in the `camel-website:antora-playbook.yml` playbook.
The content repositories are specified under the `content/sources` key.
Locate the subproject you are working on and change the `url` to point to the local checkout of the subproject, e.g.
@@ -203,19 +210,13 @@ Furthermore the content may not appear in the normal Antora structure but may be
Generally there will never be a reason to refer from one version of a component to another version.
To assure this happens without maintenance issues, leave out the version and component segments from the xref, e.g. in the `components` component
-[source,adoc]
-----
-# use lowercase xref!
-XREF:eips:enterprise-integration-patterns.adoc[]
-----
+[source,adoc,subs=+attributes]
+xref{blank}:eips:enterprise-integration-patterns.adoc[]
NOT
-[source,adoc]
-----
-# use lowercase xref!
-XREF:next@components:eips:enterprise-integration-patterns.adoc[]
-----
+[source,adoc,subs=+attributes]
+xref{blank}:next@components:eips:enterprise-integration-patterns.adoc[]
Do this no matter how many locations the component is distributed over.
@@ -230,10 +231,7 @@ Leave out the version segment.
For example, this will link to this page from anywhere in the documentation:
[source,adoc]
-----
-# use lowercase xref!
-XREF:user-manual::improving-the-documentation.adoc[]
-----
+xref:manual::improving-the-documentation.adoc[]
=== Links between subprojects
@@ -266,9 +264,6 @@ NOTE: Setting these up is WIP
Use these attributes to refer to documentation for the related subproject, e.g.
[source,adoc]
-----
-# use lowercase xref!
-XREF:{camel-version}@camel:eips:enterprise-integration-patterns.adoc[]
-----
+xref{blank}:{camel-version}@components:eips:enterprise-integration-patterns.adoc[]
-If there's a missing attribute, raise an issue rather than using a concrete version.
\ No newline at end of file
+If there's a missing attribute, please raise an issue rather than using a concrete version.
\ No newline at end of file
diff --git a/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc b/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
index 47671ba..4653637 100644
--- a/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
+++ b/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
@@ -1,42 +1,86 @@
-= Updating the website after a release of main camel, camel-spring-boot, and camel-karaf
+= Updating the website after a release
-These steps should be done only after the release is voted on and approved.
+Most steps are the same for all releases although some details may vary.
+There are several cases:
-I'm going to use the notation `<repo short name>:<path>` to indicate the file to be changed.
-For instance, `camel:docs/components/antora.yml` for the `docs/components/antora.yml` component descriptor in the main camel repository, in whatever branch is under discussion.
+* A single repository release, such as `camel-kafka-connector`.
+* A set of separately versioned repositories, such as `camel-k`, `camel-k-runtime`, and `camel-kamelets`.
+* The set of main `camel`, `camel-spring-boot`, and `camel-karaf` which are versioned together.
-== Notes on versions
+Changes in the content repositories may be done as part of release preparation, or later. Changes in the `camel-website` `antora-playbook.yml` can be supplied in a PR at any time but should be merged only after the release is voted on and approved.
-Within an Antora component, xrefs to content in the same component, whether or not they are in the same source tree or repository, should never include the `version` or `component` segment of the page id.
-Including the version will make the page non-relocatable to another version: for instance specifying `next` in the main branch will break the link when main is branched for a release.
-Including the `component` segment will redirect to the (Antora) latest version, which will typically be the last released version.
+We'll use the notation `<repo short name>:<path>` to indicate the file to be changed.
+For instance, `camel:docs/components/antora.yml` for the `docs/components/antora.yml` component descriptor in the main camel repository, in whatever branch is under discussion.
-Antora calculates the latest version as the last non-prerelease version.
-Since we are marking the main branch as prerelease, this will never be the main branch.
+//== Notes on versions
+//
+//Within an Antora component, xrefs to content in the same component, whether or not they are in the same source tree or repository, should never include the `version` or `component` segment of the page id.
+//Including the version will make the page non-relocatable to another version: for instance specifying `next` in the main branch will break the link when main is branched for a release.
+//Including the `component` segment will redirect to the (Antora) latest version, which will typically be the last released version.
+//
+//Antora calculates the latest version as the last non-prerelease version.
+//Since we are marking the main branch as prerelease, this will never be the main branch.
-== After a new release branch is created
+== After new release branches are created in all affected content repositories
-This will always be a branch from `main`.
-Changes to the new branch, say `camel-3.13.x`, will be needed.
+These will always be branches from `main`.
+Changes to all the new branches, e.g. `camel-3.13.x`, will be needed.
The changes are almost the same whether the new branch is LTS or not.
-=== Changes to the new branch (`3.13.x`) in synchronized projects
-
-For each of the projects, `camel`, `camel-karaf`, `camel-spring-boot`, locate the section for the project in the `camel-website` `antora-playbook.yml` and adjust the version in the component descriptor for each start path.
-As of writing this consists of:
-
-In `camel:docs/components/antora.yml`::
-In `camel:core/camel-core-engine/src/main/docs/antora.yml`::
-In `camel-karaf:docs/antora.yml`::
-In `camel-spring-boot/components-starter/antora.yml`::
-In `camel-spring-boot/core/antora.yml`::
-In `camel-spring-boot/docs/components/antora.yml`::
-In `camel-spring-boot/docs/spring-boot/antora.yml`::
+=== Changes to the new branches ( e.g. `camel-3.13.x`) in affected content repositories
-* Change `version` to the branch name e.g. `3.13.x`
-* Remove the `prerelease` flag line
-* If the new branch is LTS, set the display-version to e.g. `3.13.x (LTS)`.
-* If the new branch is not LTS, remove the `display-version` line.
+. Examine the `content:sources` key of the `camel-website:antora-playbook.yml` and locate the URLs of the repositories.
+. For each URL, locate the `start_path` or `start_paths` key.
+. For each start path entry, locate the `antora.yml` component descriptor at that path in the new branch in the repository.
+For each Antora component, exactly one of the associated component descriptors will have additional information beyond the name and version.
+The version will need to be updated in all associated component descriptors, and the additional information only in the one containing it.
+The primary component descriptor, having been duplicated from `main`, will specify version `next` and related properties, and will look something like this:
++
+[source,yaml]
+----
+name: camel-kafka-connector
+title: Camel Kafka Connector
+version: next
+prerelease: true
+display-version: Next (Pre-release)
+
+nav:
+- modules/ROOT/nav.adoc
+
+asciidoc:
+ attributes:
+ camel-version: 3.12.x
+ camel-k-runtime-version: 1.8.0
+ camel-kamelets-version: 0.3.0
+ prerelease: true
+----
+. Set the version to the documentation version for the new release, e.g. `0.11.0`.
+. Remove the top level `prerelease` key.
+. If the new release is LTS, set the `display-version` appropriately, e.g. `0.11.0 (LTS)`: otherwise remove the `display-version` key.
+. Consider the versions listed in `asciidoc/attributes`.
+These represent the other camel subprojects this one depends on.
+** For subprojects outside the current release set, these will not change on release.
+** For subprojects in the same release set, such as `camel`, `camel-spring-boot`, and `camel-karaf`, these versions will need to be updated to refer to the new version of the other subproject.
+. Remove `prerelease` from `asciidoc/attributes`.
+. If the release is LTS, add an `lts` attribute specifying the date out of service.
+. Build each project (e.g. `mvn clean install -Pfastinstall`) and check for generated changes that need to be committed (or undone if there are tooling problems).
+
+Since the branches with these changes have not yet been added to the Antora playbook, they may be kept on a PR fork/branch or merged into the release branch locally or in the repository.
+
+=== Playbook changes
+
+These changes must go through a PR before being merged, and it is highly advisable to build the website locally to check for problems.
+
+. As in the previous section, examine the `content:sources` key of the `camel-website:antora-playbook.yml` and locate the URLs of the repositories.
+. Under `branches` add the new branch directly under `main`, so the branches appear in reverse chronological order, newest first.
+Note that this is the git branch name, which is related to but usually not identical to the Antora component version.
+. Consult these xref:improving-the-documentation.adoc#_local_build_instructions[local build instructions].
+. Consult these xref:improving-the-documentation.adoc#_creating_a_documentation_pull_request[instructions for creating a documentation PR].
+Note that your `camel-website` will definitely need to be merged possibly after adjusting the appropriate source URLs back to the camel repositories rather than any fork repositories used for content PRs.
+
+=== Notes for specific projects
+
+==== camel-karaf
In `camel-karaf:tooling/camel-karaf-docs-maven-plugin/src/main/java/org/apache/camel/karaf/maven/ExtMvelHelper.java`::
@@ -50,86 +94,18 @@ to e.g.
[source,java]
private final static String CAMEL_VERSION = "3.13.x";
-At this point, build each project (`mvn clean install -Pfastinstall`) and check for generated changes that should be committed.
-
-NOTE: TODO: Is there a step of setting up CI or the regen bot?
-Should maven snapshots be deployed?
-
-=== Changes to other subprojects
-
-Be sure the subprojects using the latest release of main camel are aware that they need to update to the latest version, including documentation updates.
-Any reference to the main camel documentation should use a version set in the subproject antora.yml component descriptor(s).
-This may be set automatically from another source such as a maven `pom.xml`.
-
-Subproject changes are likely to involve code as well as documentation changes and need to be done by a subproject expert.
-This section only attempts to describe the documentation changes needed.
-
-In the `camel-quarkus` project examine the root `pom.xml` of every version used in the website.
-There will be a property entry like:
-
-[source,xml]
- <!-- Primary dependencies - maintained manually -->
- <camel.major.minor>3.13</camel.major.minor> <!-- run after each change: cd docs && mvnd validate -->
-
-If the camel version is removed from documentation by this release, update it to the new version.
-If the camel version is LTS consider whether it is appropriate to update it to the new version.
-If changed, follow the instructions and run mvn validate in the docs directory.
-
-=== Changes to the Antora playbook
-
-This must be done in three steps:
-
-. Add the new documentation version to the published website, leaving the previous version.
-. Wait for all subprojects such as camel-quarkus to update to using the new version, as appropriate.
-. Remove the old, previous, documentation version from the website, if appropriate.
-
-NOTE: After a release, consider whether any LTS versions are now out of service and should be removed from the documentation.
-
-==== Step 1
-
-Add the new branch to `camel-website:antora-playbook.yml` for the `content.sources` for `camel` 3 docs, `camel-karaf`, and `camel-spring-boot`.
-Add the new branch near the top of the list after the `main` branch to keep the branches listed in reverse chronological order.
-
-Test your work locally and with a PR... once it is approved and committed go on to step 2.
-
-==== Step 2
-
-Make sure all subproject participants are aware of the new release and wait for them to update the subprojects to use the new release as appropriate.
-
-==== Step 3
-
-There are two cases to consider in modifying `camel-website:antora-playbook.yml`.
-
-New LTS version::
-Release after a non-LTS release::
-* Remove the previous release branch from the sources sections for camel, camel-karaf, and camel-spring-boot.
-
-First release after an LTS release::
-* Nothing to do.
-
-=== How to test your work
-
-This process should be followed for any documentation change and is especially important for new releases.
-
-. The documentation changes will be on one or more branches in your GitHub fork(s) of camel projects.
-Make sure that the modified branch(es), say `3.13.x-feature`, and all unmodified branches are up to date in your fork.
-There may be better ways, but one way is to, in your local clone, fetch from origin, pull into each unmodified branch, and push these to your fork.
-
-. In your clone of the camel-website project, modify the playbook to use your forks of the changed branches as urls and the changed branches.
-Since you've updated your fork on unchanged branches to match origin, the other branches should be up to date.
+==== camel-quarkus
-. Build the site locally.
-.. (one time) You may need to compile platform specific Node dependencies if you are not on a Linux x86 system by running `yarn workspaces foreach install`.
-.. (one time) You may need to build the Antora ui by running `yarn build-all` or `cd antora-ui-camel && yarn build`
-.. After this running `yarn build:antora` or `yarn build` is sufficient.
+Many of the versions in the `antora.yml` component descriptor are set by the maven build from `pom.xml` properties.
+Check that these have appropriate values after running the build.
+If the build sets inappropriate values consider fixing or disabling the groovy script.
-. Your playbook and other website changes are on a branch of the `camel-website` project.
-Push this branch to your `camel-website` fork and open a PR.
-Wait for the PR preview build on Netlify and check that the build succeeded and the results look as you expect.
+== Removing obsolete component versions
-. After appropriate approvals merge your documentation source branch PRs.
+After each releease, it may be possible to remove old versions of the subprojects documentation.
+This depends on whether any current versions of other subprojects depend on the old subproject versions.
-. Update your Antora playbook by switching back to the `apache` urls and the merged branches.
-Push the result to your fork and wait for the PR preview build.
+The experimental approach is to remove the old branches from the playbook and build the site.
+If there are errors from broken xrefs pointing to the removed version, put them back.
-. Once this is satisfactory and you have the appropriate approvals merge your `camel-website` PR.
+You can also examine the component descriptors of the older versions of subprojects that depend on the current subproject, but it is not obvious how to determine which these are without looking at all of them.
diff --git a/docs/user-manual/modules/ROOT/pages/release-guide.adoc b/docs/user-manual/modules/ROOT/pages/release-guide.adoc
index 396346d..29579c4 100644
--- a/docs/user-manual/modules/ROOT/pages/release-guide.adoc
+++ b/docs/user-manual/modules/ROOT/pages/release-guide.adoc
@@ -1,6 +1,7 @@
= Release Guide
This guide covers how to create and announce a Camel release.
+Instructions on updating the website to include the new documentation version are xref:release-guide-website.adoc[here].
[[ReleaseGuide-Prequisites]]
== Prequisites
diff --git a/docs/user-manual/modules/faq/assets/images/using-getin-or-getout-methods-on-exchange/flow.png b/docs/user-manual/modules/faq/assets/images/using-getin-or-getout-methods-on-exchange/flow.png
deleted file mode 100644
index 37de500..0000000
Binary files a/docs/user-manual/modules/faq/assets/images/using-getin-or-getout-methods-on-exchange/flow.png and /dev/null differ
diff --git a/docs/user-manual/modules/faq/assets/images/using-getin-or-getout-methods-on-exchange/message-flow-in-route.png b/docs/user-manual/modules/faq/assets/images/using-getin-or-getout-methods-on-exchange/message-flow-in-route.png
deleted file mode 100644
index 07b4637..0000000
Binary files a/docs/user-manual/modules/faq/assets/images/using-getin-or-getout-methods-on-exchange/message-flow-in-route.png and /dev/null differ
diff --git a/docs/user-manual/modules/faq/pages/images/using-getin-or-getout-methods-on-exchange/flow.png b/docs/user-manual/modules/faq/images/using-getin-or-getout-methods-on-exchange/flow.png
similarity index 100%
rename from docs/user-manual/modules/faq/pages/images/using-getin-or-getout-methods-on-exchange/flow.png
rename to docs/user-manual/modules/faq/images/using-getin-or-getout-methods-on-exchange/flow.png
diff --git a/docs/user-manual/modules/faq/pages/images/using-getin-or-getout-methods-on-exchange/message-flow-in-route.png b/docs/user-manual/modules/faq/images/using-getin-or-getout-methods-on-exchange/message-flow-in-route.png
similarity index 100%
rename from docs/user-manual/modules/faq/pages/images/using-getin-or-getout-methods-on-exchange/message-flow-in-route.png
rename to docs/user-manual/modules/faq/images/using-getin-or-getout-methods-on-exchange/message-flow-in-route.png
diff --git a/docs/user-manual/modules/faq/pages/how-does-the-website-work.adoc b/docs/user-manual/modules/faq/pages/how-does-the-website-work.adoc
index 0a14e7f..99184fb 100644
--- a/docs/user-manual/modules/faq/pages/how-does-the-website-work.adoc
+++ b/docs/user-manual/modules/faq/pages/how-does-the-website-work.adoc
@@ -2,4 +2,4 @@
The website content sources are distributed across all the camel repositories, and assembled using the Antora and Hugo static site generators, configured in the https://github.com/apache/camel-website repository.
-See xref:ROOT:improving-the-documentation.adoc[Improving the documentation] for guidelines on how to contribute to this website.
+See xref:how-do-i-edit-the-website.adoc[] for instructions for simple website edits and xref:ROOT:improving-the-documentation.adoc[] for more detailed information and instructions for more complicated edits.