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 387dd31916ad CAMEL-27359: design - upgrade guides as data in the Camel 
catalog (#30566)
387dd31916ad is described below

commit 387dd31916ad20059ba54f2732109714d500b8b7
Author: Claus Ibsen <[email protected]>
AuthorDate: Sun Nov 22 16:41:14 2026 +0100

    CAMEL-27359: design - upgrade guides as data in the Camel catalog (#30566)
    
    A design proposal, design/upgrade-guides-as-data.adoc, for discussion
    before any code, plus its line in the AGENTS.md list of design docs.
    
    A new camel-package-maven-plugin goal turns the upgrade guides into JSON in
    camel-catalog: one entry per change, with its release, components, kind,
    breaking flag, summary, text as Markdown and the link to the entry on the
    website. A written rule says which entries apply to an upgrade from version
    A to version B, covering patch releases and backports: each entry has a
    unique id, and a patch-release entry has a change field with the id of the
    minor-guide entry it backports, so a backported change is listed once, and
    not at all when the version in use already has it. Checks in the build find
    mistakes in the guides, and the fixes go into the guides.
    CamelCatalog.camelUpgradeGuideEntries() and a small helper implement the
    rule, so the Camel CLI, the MCP server, IDE plugins and other tools list the
    same entries without parsing AsciiDoc.
    
    The work itself is CAMEL-27359; the first user is the upgrade view of
    CAMEL-27352. Open questions are listed at the end of the doc.
    
    Co-Authored-By: Claude Opus 5.5 <[email protected]>
---
 AGENTS.md                          |   4 +-
 design/upgrade-guides-as-data.adoc | 485 +++++++++++++++++++++++++++++++++++++
 2 files changed, 488 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index b37afd480ea6..b3a24ec1d0aa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -127,7 +127,9 @@ Camel is a large, long-lived project — code often looks 
"wrong" but exists for
    [`good-to-know.adoc`](design/good-to-know.adoc) (proposed hint rules in the 
catalog, facts per component),
    [`cli-short-commands.adoc`](design/cli-short-commands.adoc) (proposed 
resident daemon for the short commands of
    the Camel CLI, and why not a native front),
-   [`cedar.adoc`](design/cedar.adoc) (proposed `camel-cedar`, embedded Cedar 
authorization).
+   [`cedar.adoc`](design/cedar.adoc) (proposed `camel-cedar`, embedded Cedar 
authorization),
+   [`upgrade-guides-as-data.adoc`](design/upgrade-guides-as-data.adoc) 
(proposed upgrade guides as JSON in the
+   catalog, which entries apply to an upgrade).
 5. **Understand the broader context**: if a module replaced another (e.g. 
`camel-opentelemetry2`), understand what was
    intentionally changed vs. accidentally omitted.
 6. **Check if the fix reverts prior work**: if so, stop and reconsider; if 
still justified, say so in the PR description.
diff --git a/design/upgrade-guides-as-data.adoc 
b/design/upgrade-guides-as-data.adoc
new file mode 100644
index 000000000000..881d90564750
--- /dev/null
+++ b/design/upgrade-guides-as-data.adoc
@@ -0,0 +1,485 @@
+---
+title: Upgrade guides as data in the Camel catalog
+authors:
+  - "@davsclaus"
+reviewers: []
+approvers: []
+creation-date: 2026-11-21
+last-updated: 2026-11-22
+status: proposed
+see-also:
+  - "CAMEL-27359"
+  - "CAMEL-27352"
+  - "CAMEL-27351"
+replaces: []
+superseded-by: []
+---
+
+== Summary
+
+The upgrade guides 
(`docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_*.adoc`) are 
written for people
+who read them on the website, one page per minor release. A tool that helps 
with an upgrade needs the same content
+as data: the entries that apply between the version in use and the target, the 
components each entry is about,
+whether it is a removal or a deprecation, and a link to the entry on the 
website.
+
+This proposal adds a build step that turns the guides into JSON, one entry per 
change, and ships the JSON in
+`camel-catalog`, as the catalog already ships the Camel releases and the 
security advisories:
+
+[source,json]
+----
+{
+  "id": "4.22.3/camel-ftp-sftp-uses-remote-file-and-directory-names-as-given",
+  "change": 
"4.24/camel-ftp-sftp-uses-remote-file-and-directory-names-as-given",
+  "guide": "4.22",
+  "from": "4.22.2",
+  "to": "4.22.3",
+  "title": "camel-ftp - sftp uses remote file and directory names as given",
+  "components": ["camel-ftp"],
+  "kind": "change",
+  "breaking": false,
+  "summary": "The sftp component now uses a remote file or directory name 
exactly as given, also when it contains * or ?.",
+  "text": "...the entry, as Markdown...",
+  "url": 
"https://camel.apache.org/manual/camel-4x-upgrade-guide-4_22.html#_camel_ftp_sftp_uses_remote_file_and_directory_names_as_given";
+}
+----
+
+The AsciiDoc stays the source. Guide authors write it as they do today. Checks 
in the build find the mistakes of the
+guides, which are fixed in the guides, so the JSON is as accurate as the 
guides can be made. The document also defines the rule for
+choosing the entries of an upgrade from one version to another, so every tool 
lists the same entries.
+
+The point is that the format is shared. The Camel CLI, the MCP server, an IDE 
plugin, Camel Kit or a tool nobody has
+written yet can each build their own upgrade help on the same data. None of 
them has to parse AsciiDoc.
+
+== Motivation
+
+Today a tool that wants the guides parses the AsciiDoc itself:
+
+- The MCP server (`camel-jbang-mcp`) copies the guide files into its JAR at 
build time (`copy-migration-guides` in
+  its `pom.xml`). `MigrationData` splits them into sections at the `==` and 
`===` headings, and searches them with
+  BM25 for `camel_migration_guide_search`. It does not know which component an 
entry is about, or whether an entry
+  of a patch release is already in the version in use.
+- The upgrade view planned in CAMEL-27352 (the Camel CLI `camel update check` 
and a screen of the Camel TUI) needs the
+  entries between two versions, per component, so it can show only the entries 
that touch the components the
+  integration uses. The guides are not in the CLI, so it would have to parse 
them again.
+- The https://github.com/apache/camel-upgrade-recipes/[Camel Upgrade Recipes] 
automate part of a migration. They
+  would gain from knowing which guide entries a recipe covers, so a tool can 
say "this entry is done for you, these
+  you do by hand".
+- An IDE plugin, Karavan or Camel Kit would each write a third, fourth and 
fifth parser.
+
+Each parser has its own idea of where an entry starts and ends, which version 
it belongs to, and which component it is
+about. The guides have more structure than a quick parser sees:
+
+- A guide has a `==` section per release: the minor release (`== Upgrading 
Camel 4.21 to 4.22`) and the patch
+  releases of an LTS line (`== Upgrading from 4.22.2 to 4.22.3`). Some guides 
also have a `==` section that is not a
+  release (`== Camel Spring Boot`, `== Removed deprecated components`).
+- An entry is usually a `===` heading, but the 4.23 guide groups its entries 
under `=== Breaking Changes` and
+  `=== Deprecated Components and Features`, with an entry per `====` heading.
+- A change that is backported has an entry in each line it went into: the 4.18 
guide, the 4.22 guide, and the minor
+  guide of the release where it landed on main. A tool that lists all three 
tells the user the same thing three
+  times. A tool that lists the minor entry to a user who already has the 
backport tells them about a change they have.
+
+A parser in the catalog build, run once, with tests and with warnings when a 
guide does not fit the rules, is better
+than one per tool.
+
+== Goals
+
+- One JSON entry per change, with the release that brings it, the components 
it is about, its kind and a link to the
+  website.
+- A written rule for which entries apply to an upgrade from version A to 
version B, including patch releases and
+  backports, which every tool follows.
+- The JSON in `camel-catalog`, read through `CamelCatalog`, and as plain files 
in the JAR for a tool that is not
+  written in Java.
+- Data as accurate as we can make it: checks in the build that find the 
mistakes of the guides (a section in the wrong
+  guide, a missing patch release, a backport with no entry on the minor 
guide), a pass that fixes the ones there are
+  today, and a strict build afterwards, so the guides stay correct for the 
website as well as for the JSON.
+
+== Non-goals
+
+- Changing the code of a project. That is the job of the Camel Upgrade Recipes 
and `camel update run`.
+- A new authoring format. The guides stay AsciiDoc, written as today. The 
conventions in
+  <<Conventions for guide authors>> are the ones most entries follow already.
+- The upgrade view itself (CAMEL-27352). It is one user of the data, not part 
of this design.
+- The guides of Camel Spring Boot and Camel Quarkus, which live in their own 
repositories. They can produce the same
+  format later (see <<Open questions>>).
+
+== Proposal
+
+=== The files
+
+A new goal of `camel-package-maven-plugin`, `prepare-upgrade-guides`, runs in 
the normal `camel-catalog` build, next to
+`prepare-catalog`. Unlike the releases and the advisories, which are synced 
from camel-website by a profile, the
+guides live in this repository, so the JSON is generated in every build and 
committed like the other generated
+catalog files:
+
+----
+catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/upgrade-guides/
+  index.json
+  camel-4x-upgrade-guide-4_1.json
+  ...
+  camel-4x-upgrade-guide-4_24.json
+----
+
+`index.json` lists the guides:
+
+[source,json]
+----
+{
+  "schemaVersion": 1,
+  "guides": [
+    {
+      "guide": "4.22",
+      "file": "camel-4x-upgrade-guide-4_22.json",
+      "title": "Upgrade guide 4.21 -> 4.22 LTS",
+      "lts": true,
+      "url": 
"https://camel.apache.org/manual/camel-4x-upgrade-guide-4_22.html";,
+      "sections": [
+        { "from": "4.22.2", "to": "4.22.3" },
+        { "from": "4.22.1", "to": "4.22.2" },
+        { "from": "4.22.0", "to": "4.22.1" },
+        { "from": "4.21", "to": "4.22" }
+      ],
+      "entries": 214
+    }
+  ]
+}
+----
+
+Each guide file is a JSON array of entries. The 4.x guides are 2 MB of 
AsciiDoc. The JSON, with the text as Markdown,
+is about 2 MB too, and about 600 KB as stored (compressed) in the JAR.
+
+=== The entry
+
+[cols="1,1,4"]
+|===
+| Field | Type | What it is
+
+| `id`
+| string
+| The id of the entry, unique in the catalog: the release of its section, `/`, 
and the slug of its title. The release
+  is the `to` of the section: `4.24` for a minor section, `4.22.3` for a patch 
section. The slug is the title in lower
+  case, with each run of characters that are not `a-z` or `0-9` replaced by 
one `-`, and no `-` at the start or the
+  end. It has no maximum length. A second entry with the same title in one 
section gets `-2`, a third `-3`, and so
+  on (each with a warning, see <<Checks in the build>>).
+  Example: 
`4.22.3/camel-ftp-sftp-uses-remote-file-and-directory-names-as-given`.
+
+| `change`
+| string
+| The id of the change the entry is about. For an entry of a minor section, 
its own `id`: each change lands on `main`
+  once, in one minor release. For an entry of a patch section, the `id` of the 
minor entry it is a backport of (see
+  <<Backports>>), or its own `id` when there is none. The rule of <<Which 
entries apply to an upgrade>> works on
+  `change`.
+
+| `guide`
+| string
+| The minor version of the guide the entry is in: `4.22`.
+
+| `from`, `to`
+| string
+| The `==` section the entry is in. For a minor section `4.21` and `4.22`, for 
a patch section `4.22.2` and
+  `4.22.3`. A `==` section that is not a release (`== Camel Spring Boot`) 
belongs to the minor release of its guide.
+
+| `title`
+| string
+| The heading of the entry, as written.
+
+| `group`
+| string, optional
+| The `===` heading an entry is grouped under, when the entry is a `====` 
heading: `Breaking Changes`,
+  `camel-core - Enterprise Integration Patterns (EIPs)`.
+
+| `components`
+| array of strings
+| The Maven artifact ids the entry is about: `camel-ftp`, `camel-core`, 
`camel-yaml-dsl`. Empty for a general entry
+  (Java DSL, EIPs, Spring Boot).
+
+| `eips`
+| array of strings, optional
+| The EIPs an entry is about, when the heading names them (`=== Recipient 
List, Split and Multicast EIP`). A value is
+  the `name` of the EIP model in the catalog (`models/split.json`, 
`CamelCatalog.findModelNames()`): case-sensitive,
+  in camel case, such as `split` and `recipientList`.
+
+| `kind`
+| string
+| `change`, `deprecation` or `removal`. A rename (of an option, a header, a 
page, a class) is a `change`, with the old
+  and the new name in the text. There is no `addition`: the upgrade guides are 
for migration only, not for new
+  features (the upgrade guide rule of `CLAUDE.md`), so an entry about a new 
feature is a `change` too.
+
+| `breaking`
+| boolean
+| `true` when the heading or its group says it is a breaking change 
(`(Breaking change)`, `- potential breaking change`,
+  `=== Breaking Changes`).
+
+| `summary`
+| string
+| The first sentence of the entry, as plain text: for a list, a table or a 
one-line view.
+
+| `text`
+| string
+| The whole entry, as Markdown (see <<The text>>).
+
+| `url`
+| string
+| The entry on the website: the page of the guide and the anchor of the 
heading.
+|===
+
+New fields can be added in a later version of the format. A tool ignores the 
fields it does not know. A change that
+breaks a reader increases `schemaVersion`.
+
+=== From AsciiDoc to entries
+
+The goal reads each guide line by line, as `MigrationData` does today, and 
skips the content of delimited blocks
+(`----`, `....`, `====`, `|===`), so a heading inside an example is not taken 
for one.
+
+Sections::
+* `== Upgrading Camel X.Y to X.Z` is a minor section, `from` X.Y and `to` X.Z.
+* `== Upgrading from X.Y.A to X.Y.B` is a patch section. The versions are as 
written: `4.18.1 to 4.18.3` skips 4.18.2,
+  which was not released.
+* Any other `==` section belongs to the minor release of the guide.
+
+Entries::
+* A `===` heading with no `====` heading under it is one entry.
+* A `===` heading with `====` headings under it is a group. Each `====` 
heading is an entry, with the `===` heading as
+  its `group`. The text between the `===` heading and the first `====` 
heading, if any, is one more entry, titled as
+  the group.
+* The list under `Removed deprecated components` (as a `==` or a `===` 
heading) gives one entry of kind `removal` per
+  component in the list.
+
+Components::
+* The part of the heading before ` - ` or ` (` is split at `,`, `/` and ` and 
`. Each part that is a Maven artifact id of
+  this repository is a component of the entry: `=== camel-file / camel-aws2-s3 
/ camel-ibm-cos` names three.
+* A small alias file maps names that are not artifact ids: `camel-jbang` to 
the Camel CLI artifacts, `camel-sftp` and
+  `camel-ftps` to `camel-ftp`, `camel-cxf` to `camel-cxf-soap` and 
`camel-cxf-rest`. A removed component (`camel-irc`,
+  `camel-ironmq`) is not an artifact any more: its name is kept as written, as 
it is the name a project that still
+  uses it has in its `pom.xml`.
+* An entry of a group with no component in its own heading gets the components 
of the group heading:
+  `==== Split EIP - ...` under `=== camel-core - Enterprise Integration 
Patterns (EIPs)` is about `camel-core`.
+
+Kind::
+* `removal` for a heading or group with `(Removal)`, `Removed`, or the list of 
removed components.
+* `deprecation` for a heading or group with `(Deprecation)`, `(deprecated)`, 
`Deprecated` or ending in `deprecated`.
+* `change` for all other entries.
+
+URL::
+The anchor is the id Asciidoctor gives the heading on the website: `_` and the 
title in lower case, with the characters
+that are not a letter, a digit, a space, `-` or `.` removed, and each space, 
`-` or `.` replaced by `_`. A second
+heading with the same title on the page gets `_2`, as the second `=== 
camel-kafka` of the 4.19 guide does. A test
+checks the goal against the ids of a guide rendered with Asciidoctor.
+
+The goal does not use a full AsciiDoc parser. The guides use a small part of 
AsciiDoc (headings, lists, source
+blocks, tables, admonitions, `xref:`), and the line reader that 
`MigrationData` uses has worked on all of them.
+
+=== The text
+
+`text` is the entry as Markdown: a source block becomes a fenced code block 
with its language, an admonition a quote
+starting with `**NOTE:**`, an `xref:` a link to the page on the website, and a 
table a GitHub table. A table that has
+blocks inside a cell (lists, code), which Markdown tables cannot hold, becomes 
a fenced code block with the language
+`asciidoc`. So `text` is always Markdown, and the exception is marked the way 
Markdown marks any code: a tool that
+renders Markdown shows the table as source, and a tool that wants it can find 
it by the language.
+Today the 4.x guides have 294 source blocks, 121 tables, 51 admonitions and 88 
`xref:` links.
+
+Markdown reads well in a terminal, in an IDE tooltip and in a prompt for an 
AI, and most tools can render it. The
+alternative, the raw AsciiDoc, is in <<Open questions>>.
+
+=== Which entries apply to an upgrade
+
+This is the rule every tool follows, so `camel update check`, the MCP server 
and an IDE plugin agree on what an
+upgrade from version A to version B brings.
+
+A version `V` on the line `L` (its major and minor: `4.18.2` is on the line 
`4.18`) *has* an entry `e` when:
+
+* `e` is in a minor section and `e.to` is `L` or older, or
+* `e` is in a patch section of the guide of `L` and `e.to` is `V` or older.
+
+`V` *has* a change when it has an entry with that `change`. Versions are 
compared as numbers, part by part
+(`4.22.10` is newer than `4.22.9`).
+
+The entries of an upgrade from `A` to `B` are, for each change `B` has and `A` 
does not, one entry: the entry of the
+patch sections of `B`'s line when there is one (its text speaks of that line), 
else the entry of the minor section. A
+change has one entry in a minor section and at most one in the patch sections 
of each line, so there is no other
+choice to make.
+
+An example, from 4.18.2 to 4.22.3:
+
+* The entries of the minor sections of 4.19, 4.20, 4.21 and 4.22 are listed.
+* The entries of the patch sections 4.22.0 to 4.22.3 are listed.
+* The entries of the patch sections 4.18.3 to 4.18.6 are not listed for what 
they are: they are changes of the 4.18
+  line, and 4.22.3 has them only if they went into 4.22 as well, which its own 
entries say.
+* An entry of 4.19 whose change was backported to 4.18.1 is not listed: 4.18.2 
has the change already, from the
+  4.18.1 patch section, whose entry has the same `change`.
+* The `=== camel-jbang` entries of 4.20 and 4.21 are both listed. They are two 
changes with the same title, and each
+  has its own `change`.
+* `camel-ftp - sftp uses remote file and directory names as given` is in the 
4.18.6, 4.22.3 and 4.24 sections. 4.22.3
+  has it and 4.18.2 does not, so it is listed once, with the text of the 
4.22.3 entry.
+
+The rule also answers a question an upgrade tool should ask: does `B` lack a 
change `A` has? From 4.18.6 to 4.22.2,
+the sftp change above is in `A` and not in `B`, because it went into 4.22.3. A 
tool can say "4.22.2 does not have
+this fix from 4.18.6 yet, take 4.22.3". This is information for the user, as 
the entries are: each tool decides how
+to show it (a line in the CLI output, a row in a view, a field in an MCP 
answer). It is not an error.
+
+A downgrade (`B` older than `A`) has no entries. A tool says so instead of 
listing nothing.
+
+==== Backports
+
+The goal finds the minor entry of a patch entry by its title: the backport of 
a change has the same heading as the
+entry of the minor release where the change landed on `main`. That release is 
newer than the line of the patch
+section, so only the minor sections of newer guides are searched. Titles such 
as `=== camel-kafka` are in many guides
+(246 minor entries share their title with an entry of another minor guide), 
which is why the id of an entry is not its
+title alone, and why the match must find exactly one entry.
+
+When the title cannot be the same, an AsciiDoc comment under the heading names 
the minor entry. A comment is not
+shown on the website, and does not change the anchor of the heading:
+
+[source,asciidoc]
+----
+=== camel-ftp - sftp no longer treats * and ? in a name as wildcards
+// upgrade-guide-change: 
4.24/camel-ftp-sftp-uses-remote-file-and-directory-names-as-given
+----
+
+Today 242 of the 356 entries of patch sections match exactly one minor entry. 
27 match several, and 87 match none.
+An entry with no match, or with several, is its own change: a tool lists it 
next to the minor entry, one entry too
+many rather than one too few. The goal warns about both, and the pass over the 
guides fixes them (see
+<<Checks in the build>>).
+
+=== Which catalog to read
+
+The entries of an LTS line are added on `main` (the upgrade guide rule of 
`CLAUDE.md`), so a catalog knows the
+entries of the releases made before it: the 4.24.0 catalog has the entries of 
4.22.3, and not those of 4.22.4 if that
+comes later. A tool reads the catalog it ships with. When the target version 
is newer than the version of that
+catalog, compared by the full version (a 4.22.2 catalog and a 4.22.3 target 
count), the tool also loads the catalog of
+the target (`CatalogLoader`), and uses the entries of both, one per `id`, the 
newer catalog first.
+
+=== Checks in the build
+
+The JSON is only as good as the guides. Where a guide is wrong, the fix goes 
in the guide, not in a special case of
+the parser, so the website and the JSON say the same. The goal checks:
+
+* A patch section in the guide of another line, or with versions that are not 
on the line of its guide.
+* A gap in the patch sections of a line: a released patch version (from the 
releases in the catalog) that no section
+  goes to. A release with nothing to say gets a section that says `No 
changes`, which gives no entry.
+* A section version that is neither released nor the next patch release of its 
line.
+* A heading whose components it cannot place: a name that starts with `camel-` 
and is neither an artifact id, an
+  alias, nor a removed component.
+* A heading that starts with a component and goes on with no ` - ` before the 
summary (`=== camel-stomp removal`).
+* An entry of a patch section that matches no minor entry (87 today), or 
several (27 today), see <<Backports>>.
+* An `upgrade-guide-change` comment that names no entry.
+* Two entries with the same title in one section (5 today), which share an 
anchor on the website only by luck of
+  order.
+
+Some mistakes always fail the build, as they also break the page on the 
website: a delimited block that is not
+closed, and a guide that is not valid UTF-8. A heading with no text under it 
gives no entry, and a warning.
+
+The other checks start as warnings. Step 3 of <<Order of work>>, the pass over 
the guides, fixes what they find (see
+<<Mistakes in the guides today>>), and the last pull request of that step 
makes the build strict on `main`
+(`-Dcamel.upgrade-guides.strict=true` by default). From then on, a new mistake 
fails the pull request that brings it,
+as a missing generated file does today. Until then, nobody has to fix a 
warning before their pull request is merged.
+
+=== Mistakes in the guides today
+
+A prototype of the parser and the checks, run on the 4.x guides of `main` 
(2031 entries, 1702 with a component), found:
+
+* The 4.14 guide has a section `== Upgrading from 4.10.0 to 4.10.1` ("No 
changes"), copied from the 4.10 guide. It
+  should be 4.14.0 to 4.14.1. As it is, a tool would give the 4.10.1 release a 
section in the 4.14 guide.
+* The 4.8 guide has no section from 4.8.3 to 4.8.4: it goes from `4.8.2 to 
4.8.3` to `4.8.4 to 4.8.7`.
+* 87 of the 356 entries of patch sections match no minor entry, and 27 match 
several. Some are titles that changed
+  when the entry was copied, some are generic titles (`=== camel-kafka`). Some 
may be backports whose entry on the
+  minor guide is missing, which the pass checks one by one, against the 
commits.
+* Headings that name a component in a form the parser cannot split: 
`camel-stomp removal`,
+  `camel-vertx-websocket clientOptions type changed from HttpClientOptions to 
WebSocketClientOptions`,
+  `camel-opentelemetry2 — Embedded OTLP receiver ...` (an em dash), 
`camel-dynamic-router EIP component`.
+* Names that are not artifacts: `camel-simple` (the language is in 
`camel-core-languages`), `camel-cxfrs`,
+  `camel-aws`, `camel-aws2`, `camel-google`, `camel-tests`. Each becomes the 
artifact, or an alias when it is a family
+  of components.
+* Entries of Camel Spring Boot starters (`camel-jolokia-starter binds to 
loopback`, ...) in the guides of this
+  repository. They keep their place, and get `runtime` `spring-boot` (see 
<<Open questions>>).
+* Five sections with two entries of the same title, such as the two `=== 
camel-kafka` of the 4.19 guide. Both are
+  merged into one, or each gets a summary in its title.
+
+The 4.18.6 and 4.22.3 sections are for releases still to come, which the check 
allows (the next patch of the line).
+
+The pass is one pull request per kind of fix, so each is easy to review.
+
+=== Conventions for guide authors
+
+What most entries do already, written down:
+
+* Start the heading with the artifact id, then ` - ` and what changed: `=== 
camel-ftp - sftp uses remote file and
+  directory names as given`. Several components are separated by `,`.
+* Give a backported change the same heading in every guide, and a heading that 
says what changed, not only the
+  component, so it matches one entry.
+* Mark a deprecation or a removal in the heading: `(Deprecation)`, 
`(Removal)`, or group the entries under a
+  `Deprecated` or `Removed` heading.
+
+These go in the upgrade guide section of `CLAUDE.md` and in the contributing 
docs.
+
+=== The API
+
+A model in `camel-tooling-model`, `UpgradeGuideEntryModel`, with the fields of 
the entry, as `ReleaseModel` and
+`SecurityAdvisoryModel` have theirs. In `CamelCatalog`:
+
+[source,java]
+----
+/**
+ * All the entries of the upgrade guides in this catalog.
+ */
+List<UpgradeGuideEntryModel> camelUpgradeGuideEntries();
+----
+
+The rule of <<Which entries apply to an upgrade>> is in one helper in 
`camel-catalog`, `UpgradeGuideHelper`, with
+`entries(all, from, to)` and `missing(all, from, to)`, and tests built from 
the example above. A tool in another
+language reads the JSON from the `camel-catalog` JAR and follows the rule as 
written here.
+
+=== Who uses it
+
+* The MCP server reads the entries from the catalog instead of its own copy of 
the guides. Its search stays as it is,
+  over the entries, and its results gain the components and the link.
+* `camel update check` and the upgrade view of CAMEL-27352: the entries 
between the version in use and the target,
+  the ones about the components the integration uses first.
+* The Camel Upgrade Recipes could name the `change` of the entries a recipe 
covers, so a tool can say which entries are
+  automated.
+* An IDE plugin could show the entries of a component when the user changes 
its version.
+
+=== Order of work
+
+1. This design.
+2. The goal, the JSON, the model and 
`CamelCatalog.camelUpgradeGuideEntries()`, with the checks as warnings.
+3. The pass over the guides: fix the sections, align the titles of backported 
entries, add the missing entries,
+   and fix the headings the goal cannot place. Then the checks become strict.
+4. The MCP server reads the entries from the catalog.
+5. The users: `camel update check` and the upgrade view (CAMEL-27352).
+
+== Alternatives considered
+
+Each tool parses the AsciiDoc:: what happens today. Every parser makes its own 
choices, and none has the checks that
+make the guides more regular.
+
+The guides written as YAML or JSON:: the data would be exact, but the guides 
are prose for people first, written by
+many contributors in pull requests. A second format, or two copies, would 
drift.
+
+A full AsciiDoc parser (AsciidoctorJ) in the build:: exact, but a JRuby 
dependency in the catalog build for a small part
+of AsciiDoc that a line reader handles.
+
+The JSON published on the website only:: a tool without network access, or on 
an older version, could not read it,
+and the catalog is where Camel tools already look for release data.
+
+== Compatibility
+
+The format is new, so nothing breaks. `schemaVersion` and the rule "ignore 
unknown fields" leave room to add fields.
+The MCP server keeps its tool names and arguments when it moves to the catalog 
data.
+
+== Open questions
+
+* `text` as Markdown (proposed) or the raw AsciiDoc. Markdown is easier for 
every reader, and needs a converter in the
+  build. AsciiDoc is exact and needs nothing, but each tool then converts it 
or shows the markup.
+* The 3.x guides and the 2.x to 3.0 and 3.x to 4.0 migration guides, which the 
MCP server also searches. They could use
+  the same format, with fewer components found, as their headings are less 
regular.
+* Camel Spring Boot and Camel Quarkus have guides of their own. The same goal 
could run in their builds, so a tool
+  reads one format for all three.
+* A `recipes` field, with the Camel Upgrade Recipes that cover an entry, 
filled from the recipes project.
+* A `runtime` field (`spring-boot`, `quarkus`) for the entries that apply to 
one runtime only, such as the Camel
+  Spring Boot starters and the `== Camel Spring Boot` sections.
+
+== Related tickets
+
+* CAMEL-27359: the JSON in the catalog, the checks and the fixes of the guides 
(this design).
+* CAMEL-27352: the upgrade view, the first user of the data.
+* CAMEL-27351: the release data (LTS, end of life, latest patch) the upgrade 
view uses next to the entries.

Reply via email to