davsclaus opened a new pull request, #3140:
URL: https://github.com/apache/camel-kamelets/pull/3140

   _Claude Code on behalf of Claus Ibsen_
   
   ## Why
   
   Kamelets are chosen and configured by people who do not know Camel, and more 
and more by AI assistants. The assistants read only the Kamelet YAML, through 
the Camel catalog and the `camel_catalog_kamelet_list` and 
`camel_catalog_kamelet_doc` tools of the Camel CLI MCP server. Today most 
descriptions repeat the title ("Send data to Kafka topics."), and many option 
descriptions repeat the option name. Neither kind of reader can use such a 
Kamelet without reading its template, and some descriptions are wrong.
   
   ## What
   
   **1. A documentation guide**, `docs/modules/ROOT/pages/documenting.adoc`, 
linked from the index, the developer guide and AGENTS.md. It covers:
   - **Who we write for:** the integrator, and the AI assistant.
   - **Where each piece goes:** anything needed to choose or configure a 
Kamelet goes in the YAML; the partial page is for long-form help and must agree 
with the YAML.
   - **The shape of a description:** a one-sentence summary, then `Use it to`, 
`Input:`, `Output:` and `Good to know:` paragraphs. Body kinds use the words of 
the Camel message body types.
   - **Rules for options:** what each option's title, description, example and 
enum must say.
   - **`spec.dataTypes`:** how a Kamelet declares the headers it reads and sets.
   - **A checklist** for authors and reviewers.
   
   **2. Nine Kamelets rewritten to the guide**, each fact checked with `camel 
run`: `timer-source`, `aws-s3-source`, `kafka-sink`, `http-sink`, 
`jira-add-issue-sink`, `mustache-template-action`, `predicate-filter-action`, 
`set-kafka-key-action` and `dns-lookup-action`. On the way, I found and fixed 
these wrong descriptions:
   - `set-kafka-key-action` said the key comes from the body. It comes from a 
header.
   - `predicate-filter-action` said "the expression is a negation". A message 
that matches is kept.
   - `kafka-sink` said `topic` is a list; the sink writes to one topic. Its 
partial page said it connects with `SASL_SSL` by default. With the default 
`saslAuthType` of `NONE`, it uses no login and no TLS.
   - The `jira-add-issue-sink` partial page said the body must be JSON. The 
body is the text of the issue description, and the other fields come from 
headers, which are now declared in `spec.dataTypes`.
   
   **3. The `template` option of ten template actions** (freemarker, jolt, 
json-schema-validator, jslt, jsonata, mvel, string-template, velocity, 
mustache, xj) said "The inline template". It is a location: a file, a classpath 
resource or a URL. Anyone who followed the old description got a Kamelet that 
failed. `chunk-template-action` really does take the template inline, in 
Base64, and now says so.
   
   **4. A summary without changing the Kamelet spec.** The summary is the first 
paragraph of the description, so a list can show one line while the page shows 
the rest.
   - `KameletsCatalog.summary(String)` and `getKameletSummary(name)` derive it.
   - `META-INF/kamelets-index.json` has a `summary` field for each Kamelet.
   - The validator fails a summary longer than 200 characters.
   - Eight Kamelets whose first paragraph was longer get a blank line after 
their first sentence.
   
   ## For the reviewers
   
   - **#2345** cut the descriptions to one line in 2025 and moved the details 
to the partial pages. This PR asks for more in the YAML again, because the AI 
tools read only the YAML. The first paragraph stays one short sentence, so a 
list still shows one line.
   - **`spec.dataTypes` (#3117, #328):** a `default` data type is not 
documentation. Camel makes it the route's `inputType` or `outputType` and runs 
its transformer on every message. For example, with a default, `log-sink` 
turned a String into `byte[]`. This PR therefore adds only `headers` blocks, 
which change nothing at runtime. Whether #3117 should add data types with or 
without a `default` is still open.
   - `KameletsCatalogTest.testSupportedHeaders` counts changed for 
`jira-add-issue-sink` (17 → 6) and `timer-source` (2 → 1). The catalog now 
returns the headers these Kamelets declare instead of all the headers of the 
component.
   - `dns-lookup-action` is described as working. That is only true once its 
header fix in #3139 is merged, so please merge #3139 first.
   
   ## Verified
   
   - `./mvnw clean install` from the root passes. It was run twice, because the 
copy of the Kamelets into `library/camel-kamelets` happens in the install phase.
   - Each rewritten description was checked by running the Kamelet with `camel 
run --local-kamelet-dir`.
   
   Refs #328, #3117
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to