docs/user-manual/modules/ROOT/pages/release-guide-website.adoc

= Updating the website after a release

Most steps are the same for all releases, although some details may vary.
There are several cases:

* 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` and `camel-spring-boot` which are versioned together.

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.

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.

//== Notes on versions
//
//Within an Antora component, xrefs to content in the same component, whether 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 the new release, branches are created in all affected content repositories

These will always be branches from `main`.
Changes to all the new branches, e.g. `camel-3.13.x`, will be necessary.
The changes are almost the same whether the new branch is LTS or not.

=== Changes to the new branches (e.g. `camel-3.13.x`) in affected content repositories

. 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` and `camel-spring-boot`, 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.
. Find the `source-map.yml` file next to the `antora.yml` component descriptor.
It will look something like this:
+
--
[source,yml]
----
    - require: '@djencks/antora-source-map'
#      log_level: trace
      source-map:
        - url: 'https://github.com/apache/camel-kamelets.git'
          mapped-url: './../camel-kamelets'
          branches:
            - branch: main
              mapped-branch: HEAD
----
--
Change the `- branch: main` to specify the branch being released, e.g. `- branch: 0.6.x`.
. 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).
. There will also be `local-build.sh`, `source-map.yml`, and `source-watch.yml` files in the docs directory of the subproject.
These files support xref:improving-the-documentation.adoc#_local_build_instructions[local partial builds of the subproject].
In `source-map.yml`, change the `branch` value from `main` to the new git branch name for the release.

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` PR will definitely need to be merged after removing the `source-map` extension configuration used to preview the website changes.

=== Notes for specific projects

==== camel-quarkus

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.

== Removing obsolete component versions

After each release, it may be possible to remove old versions of the documentation from subprojects.
This depends on whether any current versions of other subprojects depend on the old subproject versions.

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.

You can also examine the component descriptors of 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.