This is an automated email from the ASF dual-hosted git repository.

oscerd pushed a commit to branch fix/forage-named-bean-overrides
in repository https://gitbox.apache.org/repos/asf/camel-kit.git

commit a94f7ccc83a35f0bea59b507644769595e4e9e08
Author: Andrea Cosentino <[email protected]>
AuthorDate: Mon Nov 16 10:17:13 2026 +0100

    Fix #122: describe Forage named-bean overrides from the environment and 
system properties
    
    The shared Forage guide and the camel-test configuration guide said that
    environment variables and system properties address only the default-bean
    key form and cannot target a named bean's key such as forage.myDb.jdbc.url.
    Forage does not have that limitation: ConfigModule.asNamed builds
    forage.<name>.<domain>.<prop>, envName() derives 
FORAGE_<NAME>_<DOMAIN>_<PROP>
    from it, and ConfigStore checks the environment, then the system property,
    then the properties files for named modules exactly as for default ones.
    
    Both guides now describe the named forms with the same precedence, matching
    the Forage documentation page, so generated deployment and CI guidance no
    longer steers users to properties-file edits that are not needed.
    ResourceConsistencyTest pins the corrected wording in both guides.
    
    Co-Authored-By: Claude Fable 5.1 <[email protected]>
    Signed-off-by: Andrea Cosentino <[email protected]>
---
 CHANGELOG.md                                         |  3 +++
 .../skills/camel-test/guides/test-configuration.md   |  2 +-
 .../src/main/resources/skills/shared/forage.md       | 11 ++++++-----
 .../camel/kit/generator/ResourceConsistencyTest.java | 20 ++++++++++++++++++++
 4 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0016d747..0d6f7002 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,9 @@ and this project adheres to [Semantic 
Versioning](https://semver.org/spec/v2.0.0
   longer leave a partly initialized workspace (#174).
 - A preserved Maven wrapper is reported as kept without a proposed copy and 
points to `--replace-wrapper`; the
   documentation now describes the wrapper as the exception to 
`.camel-kit/conflicts/` proposals (#174).
+- The shared Forage guide and the camel-test configuration guide no longer 
claim that environment variables and
+  system properties can override only default-bean keys: a named bean's 
`forage.myDb.jdbc.url` is overridden by
+  `FORAGE_MYDB_JDBC_URL` or `-Dforage.myDb.jdbc.url=...` with the same 
precedence (#122).
 - Preserve legitimate init layouts containing unrelated symlinks and normal 
permissions on new generated files.
 - Exclude VCS, build and dependency trees from graphs; support up to 256 MiB 
of recognized sources while retaining per-file limits and validation before XML 
sniffing.
 - Derive Claude MCP grants from the workflow manifest and validate catalog 
cache version components.
diff --git 
a/kit/camel-kit-core/src/main/resources/skills/camel-test/guides/test-configuration.md
 
b/kit/camel-kit-core/src/main/resources/skills/camel-test/guides/test-configuration.md
index 4c5e22ed..06ae2071 100644
--- 
a/kit/camel-kit-core/src/main/resources/skills/camel-test/guides/test-configuration.md
+++ 
b/kit/camel-kit-core/src/main/resources/skills/camel-test/guides/test-configuration.md
@@ -51,7 +51,7 @@ camel.component.kafka.autoOffsetReset=earliest
 
 > **Note:** the `${CITRUS_TESTCONTAINERS_*}` values above are resolved by 
 > Citrus at test runtime โ€” this `${}` shape is test-file-specific. Do NOT 
 > generalize `${}` to non-test properties files on the main runtime; 
 > camel-main resolves `{{key}}`, not `${key}` (see properties-generation.md 
 > ยง5.1).
 
-> **Forage override channels:** Forage resolves configuration with precedence 
env vars > system properties > properties files. In CI, 
`FORAGE_<DOMAIN>_<PROP>` environment variables (e.g. `FORAGE_JDBC_URL`) address 
the DEFAULT-bean key form only โ€” they can override an app's default `forage.*` 
keys without touching files, but cannot target a NAMED bean's key 
(`forage.myDb.jdbc.url`). Override a named bean's config through the properties 
file (e.g. the `forage.myDb.jdbc.*` overrides shown a [...]
+> **Forage override channels:** Forage resolves configuration with precedence 
env vars > system properties > properties files, for default and named beans 
alike. In CI, `FORAGE_<DOMAIN>_<PROP>` (e.g. `FORAGE_JDBC_URL`) overrides a 
default-bean key, and `FORAGE_<NAME>_<DOMAIN>_<PROP>` (e.g. 
`FORAGE_MYDB_JDBC_URL`, or `-Dforage.myDb.jdbc.url=...` as a system property) 
overrides the named bean's `forage.myDb.jdbc.url` without touching files. The 
`forage.myDb.jdbc.*` lines shown above are th [...]
 
 The snippet above is a fallback pattern. Prefer the route's real property keys 
and endpoint option names. For example,
 if the route uses `kafka:orders?groupId=order-writer&autoOffsetReset=latest`, 
keep the actual topic and group id and
diff --git a/kit/camel-kit-core/src/main/resources/skills/shared/forage.md 
b/kit/camel-kit-core/src/main/resources/skills/shared/forage.md
index 620f004a..995cbbb0 100644
--- a/kit/camel-kit-core/src/main/resources/skills/shared/forage.md
+++ b/kit/camel-kit-core/src/main/resources/skills/shared/forage.md
@@ -151,11 +151,12 @@ forage.myBroker.jms.pool.enabled=true
 
 Route usage: `jms:queue:orders?connectionFactory=#myBroker`.
 
-**Configuration precedence:** Forage resolves each key from, highest to 
lowest: environment variables
-(`FORAGE_<DOMAIN>_<PROP>`, e.g. `FORAGE_JDBC_URL`) > system properties 
(`-Dforage.jdbc.url=...`) >
-properties files > defaults. Env vars and system properties only address the 
DEFAULT-bean key form
-(no name segment) โ€” they cannot target a NAMED bean's key 
(`forage.myDb.jdbc.url`). Override a named
-bean's config through the properties file.
+**Configuration precedence:** Forage resolves each key from, highest to 
lowest: environment variables >
+system properties > properties files > defaults. Both override channels 
address default and named beans alike:
+`forage.jdbc.url` is overridden by `FORAGE_JDBC_URL` or 
`-Dforage.jdbc.url=...`, and a named bean's
+`forage.myDb.jdbc.url` by `FORAGE_MYDB_JDBC_URL` or 
`-Dforage.myDb.jdbc.url=...`. The variable form is the key
+upper-cased with every `.` replaced by `_` (`FORAGE_<NAME>_<DOMAIN>_<PROP>`); 
the system property is the key itself.
+Deployment and CI can therefore override a named bean without editing the 
properties file.
 
 ## Catalog queries (never load the whole file)
 
diff --git 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java
 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java
index 52a9950f..674bb796 100644
--- 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java
+++ 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java
@@ -1748,6 +1748,26 @@ class ResourceConsistencyTest {
                 "The Forage compatibility table must be rendered from 
distribution.properties");
     }
 
+    @Test
+    void forageGuidesDescribeNamedBeanOverrideChannels() throws IOException {
+        Path skills = 
repositoryRoot().resolve("kit/camel-kit-core/src/main/resources/skills");
+        String forage = Files.readString(skills.resolve("shared/forage.md"));
+        String testConfiguration = 
Files.readString(skills.resolve("camel-test/guides/test-configuration.md"));
+
+        for (String guide : List.of(forage, testConfiguration)) {
+            // Forage resolves FORAGE_<NAME>_<DOMAIN>_<PROP> and 
-Dforage.<name>.<domain>.<prop> for named beans
+            // with the same precedence as the default-bean form (#122).
+            assertContainsAll(guide,
+                    "FORAGE_<NAME>_<DOMAIN>_<PROP>",
+                    "FORAGE_MYDB_JDBC_URL",
+                    "-Dforage.myDb.jdbc.url=");
+            assertFalse(guide.contains("cannot target a NAMED bean"),
+                    "Named-bean keys are overridable from the environment and 
system properties (#122)");
+            assertFalse(guide.contains("DEFAULT-bean key form"),
+                    "The default-bean-only restriction does not exist in 
Forage (#122)");
+        }
+    }
+
     @Test
     void commandReferenceDefaultsMatchTheDistribution() throws IOException {
         DistributionConfig distribution = DistributionConfig.loadBundled();

Reply via email to