CAMEL-23701: Make generated archetype projects more AI-relevant by k-krawczyk · Pull Request #25409 · apache/camel

k-krawczyk · 2026-08-08T08:28:31Z

Summary

Applies the same treatment as CAMEL-23702 (#24063), but to the Maven archetypes instead of the JBang export.

Renames ReadMe.txt to README.md in all six archetypes and rewrites the content in Markdown, with the documentation links refreshed to https and to the current camel.apache.org/manual/writing-components.html location.
Adds an AGENTS.md to every generated project: the Apache Camel LLM index (https://camel.apache.org/llms.txt), the .html -> .md documentation trick, a pointer to the Camel CLI and the Camel MCP server with an explicit "do not invent component URIs or options" instruction, plus the project layout, the build/run commands and the conventions of that archetype.
Updates the six archetype-metadata.xml file sets accordingly — the readme is listed explicitly there, so the rename alone would have silently dropped it.
Adds a camel-archetypes entry to the upgrade guide. Since 4.22.0 is being released, this creates camel-4x-upgrade-guide-4_23.adoc and links it from the upgrade guide index.
camel-archetype-spring states in both generated files that the archetype is deprecated, pointing at Camel on Spring Boot or camel init.

Drive-by fix

camel-archetype-api-component declared its readme in the __artifactId__-component/ file set while the file actually lives at the project root, so no readme was generated at all. Reproduced against the released archetype:

mvn archetype:generate -DarchetypeGroupId=org.apache.camel.archetypes \
  -DarchetypeArtifactId=camel-archetype-api-component -DarchetypeVersion=4.21.0 ...

produces a project with pom.xml and the two modules, and no readme. This PR moves the entry to a root file set, so the readme is generated again.

Notes

The .md file sets are deliberately left unfiltered, as ReadMe.txt was. Markdown headings start with #, which is the Velocity directive prefix, so the generated docs are kept free of interpolation rather than risking mangled output. Consequently the content uses no ${artifactId}-style placeholders.

Verification

./mvnw install -Dquickly -f archetypes/pom.xml — BUILD SUCCESS.
mvn archetype:generate run for all six archetypes against the locally installed 4.22.0-SNAPSHOT: README.md and AGENTS.md are generated at the root of every project, with no unresolved ${...} or __x__ tokens.
The generated content was checked against the actual generated trees (MainApp / MyRouteBuilder, MyApplication / MyBean / MyConfiguration, camel-context.xml, META-INF/services/.../<scheme>, the DataFormat implementation), so it does not describe files that are not there.
apache-rat-plugin:check on the archetypes module: 0 unapproved (**/*.md is excluded in the root POM).
All referenced URLs return HTTP 200, including the .md variant of the manual page.

The archetype integration tests under src/test/resources/projects-disabled are disabled, so verification was done by generating projects manually as described above.

Reported by Claude Code on behalf of Karol Krawczyk

Rename ReadMe.txt to README.md in all six Camel archetypes and rewrite the content in Markdown, with the documentation links refreshed to https. Each generated project now also gets an AGENTS.md with guidance for AI coding assistants: the Apache Camel LLM index (https://camel.apache.org/llms.txt), the .html -> .md documentation trick, a pointer to the Camel CLI and the Camel MCP server, plus the project layout, the build/run commands and the conventions that apply to that archetype. This also fixes camel-archetype-api-component, which declared its readme in the __artifactId__-component file set while the file lives at the project root, so no readme was generated at all. Co-authored-by: Claude <noreply@anthropic.com>

orpiske

I did a quick manual review and it looks good to me. Thanks @k-krawczyk !

github-actions · 2026-08-08T13:35:34Z

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

First-time contributors require MANUAL approval for the GitHub Actions to run
You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

davsclaus

Nice work — this is a clean, well-structured PR that follows the pattern established by #24063 (JBang export). The camel-archetype-api-component bug fix is confirmed valid (the ReadMe.txt was declared in the __artifactId__-component/ fileSet but the file lives at the project root, so no readme was ever generated).

One required change: the upgrade guide entry needs to move to the 4.23 guide since 4.22.0 is being built and released. The camel-4x-upgrade-guide-4_23.adoc file doesn't exist yet, so it will need to be created.

Minor suggestions (non-blocking):

The camel-archetype-spring AGENTS.md could mention that this archetype is deprecated and suggest Spring Boot instead, so AI agents don't invest effort in a deprecated project unknowingly.
The camel-archetype-dataformat AGENTS.md reference link points to writing-components.html — inherited from the old readme and probably the closest available page, but slightly off-target for data formats.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

davsclaus · 2026-08-08T13:39:18Z

+(`https://camel.apache.org/llms.txt`), the Camel CLI and the Camel MCP server.
+
+The `camel-archetype-api-component` archetype also generates its readme again: the file was declared
+in the wrong file set and was therefore silently skipped.


This entry should be in camel-4x-upgrade-guide-4_23.adoc instead — 4.22.0 is being released, so this change will ship in 4.23.

davsclaus · 2026-08-08T13:40:00Z

Just mind that 4.22.0 is released soon so this PR will go into 4.23. But we need to wait until main branch has been prepared for this.

github-actions · 2026-08-08T13:51:52Z

🧪 CI tested the following changed modules:

archetypes/camel-archetype-api-component
archetypes/camel-archetype-component
archetypes/camel-archetype-dataformat
archetypes/camel-archetype-java
archetypes/camel-archetype-main
archetypes/camel-archetype-spring
docs

🔬 Scalpel shadow comparison — Scalpel: 7 tested, 0 compile-only — current: 6 all tested

Maveniverse Scalpel detected 7 affected modules (current approach: 6).

⚠️ Modules only in Scalpel (1)

docs

Skip-tests mode would test 7 modules (7 direct + 0 downstream), skip tests for 0 (generated code, meta-modules)

Modules Scalpel would test (7)

camel-archetype-api-component
camel-archetype-component
camel-archetype-dataformat
camel-archetype-java
camel-archetype-main
camel-archetype-spring
docs

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

All tested modules (7 modules)

Camel :: Archetypes :: API Component
Camel :: Archetypes :: Component
Camel :: Archetypes :: Data Format
Camel :: Archetypes :: Java Router
Camel :: Archetypes :: Main
Camel :: Archetypes :: Spring XML Based Router (deprecated)
Camel :: Docs

⚙️ View full build and test results

Move the upgrade guide entry to a new camel-4x-upgrade-guide-4_23.adoc, as 4.22.0 is being released and this change ships in 4.23, and link the new guide from the upgrade guide index. Also apply the two review suggestions: the camel-archetype-spring readme and AGENTS.md now say that the archetype is deprecated and point at Camel on Spring Boot or the Camel CLI, and the camel-archetype-dataformat docs reference the data format manual page next to the writing-components page. Co-authored-by: Claude <noreply@anthropic.com>

k-krawczyk · 2026-08-08T22:08:13Z

Thanks @davsclaus, @orpiske, @oscerd and @Croway for the reviews. All three points are addressed in f9b9947.

Required change — upgrade guide moved to 4.23. The entry is now in a new camel-4x-upgrade-guide-4_23.adoc, created with the same header as the other guides and a == Upgrading Camel 4.22 to 4.23 section, and removed from the 4.22 guide. I also added the xref for it in camel-4x-upgrade-guide.adoc, otherwise the new page would be orphaned from the index.

On the timing: I created the 4.23 guide here so the PR is complete, but I understand the merge should wait until main has been prepared for 4.23. If you would rather create that file yourself as part of preparing the branch, say so and I will drop it from this PR and rebase.

Suggestion 1 — deprecated Spring archetype. Both the README.md and the AGENTS.md of camel-archetype-spring now state that the archetype is deprecated and point at Camel on Spring Boot or camel init, so an agent knows before investing effort. Good catch.

Suggestion 2 — data format link. The camel-archetype-dataformat docs now reference https://camel.apache.org/manual/data-format.html for the concept, next to the existing writing-components page for the implementation details. Link verified.

Re-verified after the change: archetypes rebuild, apache-rat-plugin:check reports 0 unapproved, and I regenerated projects from the spring and dataformat archetypes to confirm the new content lands correctly.

Reported by Claude Code on behalf of Karol Krawczyk

atiaomar1978-hub

Code review (Bugbot + Grok)

AI-generated review on behalf of @atiaomar1978-hub

Solid follow-up to CAMEL-23702 / #24063 — the README.md + AGENTS.md direction for archetypes is exactly what AI-assisted contributors need. The api-component readme fileSet fix is a real bug fix (verified: readme was silently dropped). Velocity left unfiltered for # headings is the right call.

Bugbot: no bugs found.

Grok + manual check: a few doc accuracy issues undermine the AI-guidance goal — mostly packaged path layout in java/main archetypes and one incorrect registration hint. Details in inline comments.

Verdict: Request changes on the inline items; happy to re-review once fixed and CI is green.

atiaomar1978-hub · 2026-08-08T23:59:56Z

+
+## Project layout
+
+- `src/main/java/MyRouteBuilder.java` — the Camel routes.


These paths omit the package directory. The java sources fileSet uses packaged="true", so generated projects place classes under src/main/java/<package>/MyRouteBuilder.java and .../MainApp.java, not at the src/main/java/ root.

Please use <package>/MyRouteBuilder.java (or src/main/java/<package>/...) so agents don't create default-package files.

atiaomar1978-hub · 2026-08-08T23:59:56Z

+
+## Conventions
+
+- Add routes as `RouteBuilder` classes and register them with `Main` (or let component scanning pick them up).


MainApp registers routes explicitly via main.configure().addRoutesBuilder(new MyRouteBuilder()) — there is no component/package scanning in this archetype.

Suggest: "Add routes as RouteBuilder classes and register them on Main the same way as MyRouteBuilder." Drop the scanning clause to avoid misleading agents.

atiaomar1978-hub · 2026-08-08T23:59:56Z

+# Camel Java Router Project
+
+A standalone Apache Camel application generated from the `camel-archetype-java` Maven archetype.
+Routes live in `src/main/java/MyRouteBuilder.java` and are started by `src/main/java/MainApp.java`.


Same packaged-layout issue as AGENTS.md: with packaged="true", routes and MainApp live under src/main/java/<package>/, not directly under src/main/java/. Align README with the actual generated tree.

atiaomar1978-hub · 2026-08-08T23:59:56Z

+
+## Project layout
+
+- `src/main/java/MyRouteBuilder.java` — the Camel routes.


The main archetype also uses packaged="true" for Java sources. Listing flat src/main/java/MyRouteBuilder.java, MyApplication.java, etc. will mislead agents — please document src/main/java/<package>/... (same for the test class on line 18).

atiaomar1978-hub · 2026-08-08T23:59:56Z

+
+## Conventions
+
+- Implement both `marshal` and `unmarshal`, and stream from the given `InputStream`/`OutputStream` instead of buffering whole messages where possible.


Worth adding the actual registration hook from the generated template: @org.apache.camel.spi.annotations.Dataformat("<scheme>") on the DataFormat class (plus keeping getDataFormatName() in sync). This archetype does not use a META-INF/services file — agents may invent one without this hint.

atiaomar1978-hub · 2026-08-08T23:59:56Z

+## Conventions
+
+- The endpoint configuration and the API method proxies are generated at build time from the API signatures — change the API or the signature files rather than editing generated sources.
+- Annotate the endpoint with `@UriEndpoint` and its options with `@UriPath`, `@UriParam` and `@Metadata`.


Minor clarity: line 27 says proxies/config are generated — this line then says "Annotate the endpoint with @UriEndpoint..." which could imply editing generated code.

Suggest splitting: hand-written endpoint/configuration classes may use @UriEndpoint / @UriParam; generated API proxies and collections from camel-api-component-maven-plugin should not be hand-edited.

atiaomar1978-hub · 2026-08-08T23:59:56Z

+See the xref:camel-upgrade-recipes-tool.adoc[documentation] page for details.
+====
+
+== Upgrading Camel 4.22 to 4.23


Creating/linking the 4.23 upgrade guide while main is still on 4.22.0-SNAPSHOT may be premature (see @davsclaus feedback on similar PRs). Fine to keep the file in this PR, but consider holding merge until main is bumped to 4.23 — otherwise the index advertises a 4.23 guide from a 4.22 tree.

atiaomar1978-hub · 2026-08-09T00:02:08Z

Test coverage follow-up

AI-generated on behalf of @atiaomar1978-hub

Checked automated test coverage for this PR — no test files are added or modified. Verification is manual only (as noted in the PR description). That gap is worth addressing given the api-component readme regression this PR fixes.

Current state

Area	Coverage
This PR	0 test file changes across 26 files
Archetype ITs	Exist under `src/test/resources/projects-disabled/` in all 6 archetypes — `projects-disabled` means they do not run in CI (Maven archetype plugin expects `projects/`)
JBang precedent (CAMEL-23702 / #24063)	`ExportTest.shouldGenerateContent` and `shouldGenerateJavaContent` assert `AGENTS.md` and `readme.md` exist after export — automated guard for the same feature on the JBang side
Archetypes module	`archetype.test.skip=true` under `skipTests`, `fastinstall`, and `release` profiles

What manual verification covers (per PR)

✅ mvn archetype:generate for all six archetypes
✅ README.md + AGENTS.md present at project root
✅ No unresolved ${...} / __x__ tokens
✅ URL checks

What is not guarded by CI

README.md / AGENTS.md emitted at all (regression like api-component readme in wrong fileSet)
api-component readme at project root vs under *-component/ module
Doc content accuracy (packaged paths, @Dataformat, etc.)
Upgrade guide index linkage

Suggestions (pick one — ordered by ROI)

Option A — Minimal archetype IT (recommended)
Rename projects-disabled → projects for at least build-it goal on each archetype (or start with api-component + java). Extend the generated-project assertion to verify:

README.md exists at project root
AGENTS.md exists at project root
no ReadMe.txt
(api-component) README.md NOT only under *-component/

This would have caught the pre-4.22 api-component bug automatically.

Option B — Shared unit test in archetypes/ parent
One parameterized JUnit test (similar spirit to ExportTest) that runs archetype:generate into a temp dir for each archetype artifactId and asserts the two markdown files exist. Keeps ITs disabled but adds a fast smoke test in default CI.

Option C — Follow-up JIRA
If enabling ITs is blocked on ARCHETYPE-574 (noted in archetype.properties), open a follow-up to re-enable once fixed — but Option B could land independently.

Verdict on test coverage

Insufficient for merge without follow-up — acceptable for docs-only archetype change if manual verification is repeated each release, but not ideal for a change whose main bug was silent fileSet misconfiguration. Recommend Option A or B in this PR or an immediate follow-up before 4.23.

Happy to re-review if tests are added.

atiaomar1978-hub · 2026-08-09T00:02:09Z

      </includes>
    </fileSet>

+    <!-- project root docs -->


Test coverage: This fileSet fix is exactly the kind of regression automated archetype ITs would catch — before this PR, ReadMe.txt was listed under artifactId-component/ while the file lived at project root, so no readme was generated (reproduced on 4.21.0). Consider adding/re-enabling a build-it archetype IT that asserts README.md and AGENTS.md exist at the generated project root.

atiaomar1978-hub · 2026-08-09T00:02:10Z

@@ -0,0 +1,27 @@
+# AGENTS.md


Test coverage: No automated test validates generated AGENTS.md presence or content. JBang ExportTest already asserts AGENTS.md exists after export (#24063). Archetypes have IT scaffolding under src/test/resources/projects-disabled/ but it is disabled — a minimal smoke IT per archetype would lock this in.

orpiske approved these changes Aug 8, 2026

View reviewed changes

oscerd approved these changes Aug 8, 2026

View reviewed changes

Croway approved these changes Aug 8, 2026

View reviewed changes

github-actions Bot added docs tooling-maven labels Aug 8, 2026

davsclaus requested changes Aug 8, 2026

View reviewed changes

atiaomar1978-hub suggested changes Aug 8, 2026

View reviewed changes

atiaomar1978-hub reviewed Aug 9, 2026

View reviewed changes


		## Project layout

		- `src/main/java/MyRouteBuilder.java` — the Camel routes.


		## Conventions

		- Add routes as `RouteBuilder` classes and register them with `Main` (or let component scanning pick them up).


		## Conventions

		- Implement both `marshal` and `unmarshal`, and stream from the given `InputStream`/`OutputStream` instead of buffering whole messages where possible.

Uh oh!

Conversation

k-krawczyk commented Aug 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Drive-by fix

Notes

Verification

Uh oh!

orpiske left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 8, 2026

Uh oh!

davsclaus left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davsclaus commented Aug 8, 2026

Uh oh!

github-actions Bot commented Aug 8, 2026

Uh oh!

k-krawczyk commented Aug 8, 2026

Uh oh!

atiaomar1978-hub left a comment

Choose a reason for hiding this comment

Code review (Bugbot + Grok)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

atiaomar1978-hub commented Aug 9, 2026

Test coverage follow-up

Current state

What manual verification covers (per PR)

What is not guarded by CI

Suggestions (pick one — ordered by ROI)

Verdict on test coverage

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

k-krawczyk commented Aug 8, 2026 •

edited

Loading