This is an automated email from the ASF dual-hosted git repository.
jamesnetherton pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
The following commit(s) were added to refs/heads/main by this push:
new 30b1ba7b5f Add AGENTS.md & CLAUDE.md
30b1ba7b5f is described below
commit 30b1ba7b5fd76cfe34a9f4ee36b0e959329f8e67
Author: James Netherton <[email protected]>
AuthorDate: Tue Mar 3 12:53:47 2026 +0000
Add AGENTS.md & CLAUDE.md
---
AGENTS.md | 251 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 1 +
2 files changed, 252 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..1652f63dae
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,251 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+# Apache Camel Quarkus - AI Agent Guidelines
+Rules & guidelines for AI agents working on this codebase.
+
+## Project Overview
+Apache Camel Quarkus provides Quarkus extensions for Apache Camel components,
enabling users to build integration applications with fast boot times and low
memory footprints.
+
+## What NOT to do
+- Do NOT directly modify generated files under `docs/modules` or
`src/main/generated`
+- Do NOT use dynamic class loading or reflection (impacts native compilation)
+- Do NOT introduce Spring Boot or Spring unless explicitly required
+
+## Technology Stack
+- Java 17+
+- GraalVM 25+ / Mandrel 25+
+- Maven 3.9.11+ (For convenience the maven wrapper is provided in the root
directory and can be invoked as `./mvnw` or `./mvnw.cmd`)
+- Apache Camel 4.x, Quarkus 3.x. Check `pom.xml` for the current Camel, and
Quarkus versions used.
+
+## Repository Structure
+```
+extensions/ # Native-supported Camel component extensions
+extensions-jvm/ # JVM-only extensions (not yet native-compatible)
+extensions-core/ # Core Camel Quarkus extensions (core, yaml-dsl, etc.)
+extensions-support/ # Shared support libraries used by multiple extensions
+integration-tests/ # Integration tests JVM + native
+integration-test-groups/ # Groupings of integration tests, primarilly for
boosting CI speed & efficiency
+integration-tests-jvm/ # JVM-only extension integration tests
+integration-tests-support/ # Shared test utilities and test containers support
+poms/bom/ # Runtime Bill of Materials
+poms/bom-deployment/ # Deployment Bill of Materials
+tooling/ # Maven plugin, scripts, templates, and tooling
+catalog/ # Camel Quarkus catalog
+docs/ # AsciiDoc documentation (Antora-based)
+examples/ # Example projects (separate repo: camel-quarkus-examples)
+```
+
+## Key Files
+- `pom.xml` - Project Maven dependency version properties and test container
image names
+- `poms/bom/pom.xml` - Runtime dependencies BOM
+- `poms/bom-test/pom.xml` - Test dependencies BOM
+- `tooling/scripts/test-categories.yaml` - Test categorization for GitHub
Actions CI
+- `docs/antora/antora.yml` - Antora documentation metadata. Note that
`docs/local-build.sh` relies on an external `camel-website` repository and is
not intended for self-contained local documentation generation within this
project.
+
+## Build Commands
+```bash
+./mvnw clean install -Dquickly # fast build, no tests
+./mvnw clean install -T1C -Dquickly # parallel fast build, no tests
+./mvnw clean install # full build with JVM tests
+./mvnw clean install -Dnative -Ddocker # full build with native tests
(very slow, -Ddocker can usually be omitted on MacOS)
+./mvnw clean install -pl extensions/kafka -am # single extension
+./mvnw process-resources -Pformat # format code & update metadata
+```
+
+**Tip:** Use `mvnd` (Maven Daemon) for faster builds. Use `-T1C` for parallel
builds (1 thread per CPU core).
+
+## Testing Commands
+```bash
+./mvnw test # unit tests
+./mvnw verify # integration tests JVM mode
+./mvnw verify -Dnative -Ddocker # integration tests JVM + native mode
(-Ddocker can usually be omitted on MacOS)
+./mvnw test -Dtest=MyTest # specific test
+./mvnw test -pl integration-tests/kafka # specific module
+```
+
+## Extension Structure
+```
+extensions/kafka/
+├── pom.xml # Parent POM
+├── runtime/
+│ ├── pom.xml
+│ └── src/
+│ ├── main/java/org/apache/camel/quarkus/component/kafka/
+│ ├── main/resources/META-INF/quarkus-extension.yaml
+│ └── main/doc/ # Extension documentation
+│ ├── configuration.adoc
+│ └── usage.adoc
+└── deployment/
+ ├── pom.xml
+ └── src/
+ ├── main/java/org/apache/camel/quarkus/component/kafka/deployment/
+ │ └── KafkaProcessor.java
+ └── test/java/
+```
+
+### Naming Conventions
+Classes:
+- Deployment: `*Processor.java` for build-time processing `@BuildStep`
+- Runtime: `*Recorder.java` for recording and producing `RuntimeValue` used in
deployment build steps
+- Runtime: `*BuildTimeConfig.java` for `ConfigPhase.BUILD_TIME` &
`ConfigPhase.BUILD_AND_RUN_TIME_FIXED` annotated `@ConfigMapping` interfaces
+- Runtime: `*RunTimeConfig.java` for `ConfigPhase.RUN_TIME` annotated
`@ConfigMapping` interfaces
+- Runtime: `*Substitutions.java` for GraalVM substitutions that live in
`src/main/java/.../graal/`
+- Tests: `*Test.java` (JUnit 6), `*IT.java` for native tests
+
+Packages:
+- Runtime: `org.apache.camel.quarkus.component.<name>`
+- Deployment: `org.apache.camel.quarkus.component.<name>.deployment`
+
+Annotations:
+- `@BuildStep` for deployment processors
+- `@Record(ExecutionTime.STATIC_INIT)` for static init
+- `@Record(ExecutionTime.RUNTIME_INIT)` for runtime init
+- Recorder classes are annotated with `@Recorder`
+
+Configuration:
+- `@ConfigRoot(phase = ConfigPhase.BUILD_TIME)` for build-time configuration
(read during build, baked into native image)
+- `@ConfigRoot(phase = ConfigPhase.RUN_TIME)` for runtime configuration (can
be changed at runtime)
+- `@ConfigRoot(phase = ConfigPhase.BUILD_AND_RUN_TIME_FIXED)` for config read
at build time but also available at runtime (value cannot change)
+- Build-time config: extension enablement & configuration options used to
bootstrap components at build time
+- Runtime config: connection strings, credentials, timeouts, dynamic behavior
+- Prefer runtime config when possible for flexibility; use build-time only
when necessary for native compilation
+
+Maven version properties:
+- `artifactId.version` for general version properties
+- `*-maven-plugin.version` for plugin version properties
+- Where appropriate, use `@sync` comments to automatically update version
properties
+- Dependency versions MUST always be defined in the root project pom.xml
+
+## Creating Extensions
+
+### 1. Scaffold Extension
+For extensions providing native support:
+
+```bash
+./mvnw cq:create -N -Dcq.artifactIdBase=kafka
+```
+
+For extensions providing JVM only support:
+```bash
+./mvnw cq:create -N -Dcq.artifactIdBase=kafka -Dcq.nativeSupported=false
+```
+
+### 2. Add to Test Categories (native only)
+Add the extension name to `tooling/scripts/test-categories.yaml`. Test
categories should not be overloaded with too many extensions. But should be
'balanced' to ensure each one completes in roughly the same time as others.
+
+### 3. Review Extension Metadata
+View
`extensions/kafka/runtime/src/main/resources/META-INF/quarkus-extension.yaml`
+
+Update / sync with:
+```bash
+./mvnw -N cq:update-quarkus-metadata
+```
+
+### 4. Complete Integration Tests
+Follow `docs/modules/ROOT/pages/contributor-guide/extension-testing.adoc`
+
+### 5. Add Documentation
+Follow
`docs/modules/ROOT/pages/contributor-guide/extension-documentation.adoc`.
+
+After making changes, run the following from the project root to sync and
regenerate the project documentation:
+```bash
+./mvnw -pl extensions/kafka/deployment process-classes
+```
+
+### 6. Format & style
+```bash
+./mvnw process-resources -Pformat
+```
+
+## Integration Tests
+Tests use the Quarkus test framework based on JUnit 6.
+
+### Test Structure
+Follow `docs/modules/root/contributor-guide/extension-testing.adoc`.
+
+JVM mode tests should be annotated with `@QuarkusTest`.
+
+```java
+@QuarkusTest
+class KafkaTest {
+ // test code
+}
+```
+
+Native mode tests should extend the JVM mode test and be annotated with
`@QuarkusIntegrationTest`.
+
+```java
+@QuarkusIntegrationTest
+class KafkaIT extends KafkaTest {
+}
+```
+
+## Troubleshooting Native Build Failures
+Native compilation with GraalVM requires explicit registration of classes,
resources, and proxies. Register these in the deployment module's
`*Processor.java` using `@BuildStep` methods. Common patterns:
+
+| Issue | Symptom | Build item | Example |
+|-------|---------|------------|---------|
+| Reflection | `ClassNotFoundException` / `NoSuchMethodException` in native
mode | `ReflectiveClassBuildItem` |
`extensions/sql/deployment/.../SqlProcessor.java` |
+| Missing resources | `FileNotFoundException` in native mode |
`NativeImageResourceBuildItem` / `NativeImageResourceDirectoryBuildItem` |
`extensions/xj/deployment/.../XJProcessor.java` |
+| Resource bundles | `MissingResourceException` in native mode |
`NativeImageResourceBundleBuildItem` |
`extensions/fhir/deployment/.../FhirProcessor.java` |
+| Proxy classes | `ClassNotFoundException` for proxies |
`NativeImageProxyDefinitionBuildItem` |
`extensions/influxdb/deployment/.../InfluxdbProcessor.java` |
+| Service providers | `ServiceConfigurationError` in native mode |
`ServiceProviderBuildItem` | `extensions/fop/deployment/.../FopProcessor.java` |
+
+Use `CombinedIndexBuildItem` to discover classes at build time — see
`extensions/servicenow/deployment/.../ServicenowProcessor.java`.
+
+See also https://quarkus.io/guides/writing-extensions.
+
+## Common Tasks
+
+### Update Camel Version
+Edit both the project `camel-dependencies` parent version and properties in
root `pom.xml`:
+
+1. Parent `camel-dependencies` version (e.g., `<version>4.18.0</version>`)
+2. Property `camel.major.minor` (e.g.,
`<camel.major.minor>4.18</camel.major.minor>`)
+3. Property `camel.version` (defined as `${camel.major.minor}.0`)
+
+### Update Quarkus Version
+Edit `quarkus.version` in the project root `pom.xml`.
+
+### Sync Dependency Versions
+**When to sync dependency versions**: Whenever the Camel or Quarkus version is
updated. Or when version properties are updated that influence other properties
annotated with `@sync` comments.
+
+```bash
+./mvnw cq:sync-versions -N
+```
+
+### Regenerate camel-quarkus-bom
+**When to regenerate:** Whenever a dependency version is updated in the root
`pom.xml` or a new dependency is added to the project in `poms/bom/pom.xml`.
+
+```bash
+./mvnw clean install -pl poms/bom
+```
+
+### Promote an extension from JVM-only support to Native mode support
+```bash
+./mvnw -N cq:promote -Dcq.artifactIdBase=kafka
+```
+
+## Commit Messages
+Reference GitHub issues when applicable.
+```
+Fixes #issueNumber. Brief description of the change
+
+Longer detailed explanation of changes made.
+```
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
