[
https://issues.apache.org/jira/browse/CAMEL-26344?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Federico Mariani reassigned CAMEL-26344:
----------------------------------------
Assignee: Federico Mariani
> camel-jbang - plugin add: select community plugin versions built for the
> installed CLI's minor line
> ---------------------------------------------------------------------------------------------------
>
> Key: CAMEL-26344
> URL: https://issues.apache.org/jira/browse/CAMEL-26344
> Project: Camel
> Issue Type: Improvement
> Components: camel-jbang
> Reporter: Federico Mariani
> Assignee: Federico Mariani
> Priority: Major
>
> h3. Problem
> {{camel plugin add <name>}} registers community plugins with Maven {{LATEST}}
> when no version is given. The only load-time check is a minimum version
> ({{firstVersion}} in {{PluginHelper.versionCheck}}). Neither can express
> "this release is built for Camel 4.22.x", so:
> * On CLI 4.23.0, {{LATEST}} (Forage 1.6.2, built for 4.22) fails on {{camel
> run}} with {{IllegalArgumentException: Unsupported runtime jbang}}. The
> {{jbang}} run runtime is new in 4.23 (#26226).
> * Once Forage 1.7.0 (built for 4.23, KaotoIO/forage#533) is published, 4.22
> LTS users will get it by default.
> Every published plugin release already records the Camel version it was built
> against: the version of its {{org.apache.camel:camel-jbang-core}} dependency
> (scope {{provided}}) in the resolved POM. Camel can therefore choose a
> matching release for existing plugins without new metadata:
> ||Plugin release||camel-jbang-core in the resolved POM||
> |Forage 1.4.0 / 1.4.1 / 1.4.2|4.18.3 / 4.18.4 / 4.18.5|
> |Forage 1.6.0 / 1.6.1 / 1.6.2|4.22.0 / 4.22.1 / 4.22.2|
> |Forage 1.7.0 (upcoming)|4.23.0|
> |kit 0.3.0 / 0.3.1|4.18.0|
> |kit 0.4.0 / 0.4.1|4.22.0 / 4.22.1|
> h3. Proposal
> For each candidate release, read its resolved POM through the existing Maven
> resolver, so repositories, mirrors, {{--repos}}, settings and offline mode
> all apply. Take the supported range from:
> # the property {{camel.jbang.plugin.camel-versions}} (Maven range syntax,
> e.g. {{[4.23.0,4.24.0)}}): *declared*. Forage 1.7.0 publishes it.
> # otherwise the {{camel-jbang-core}} dependency version, as its minor line
> ({{4.22.2}} -> {{[4.22.0,4.23.0)}}): *inferred*
> # otherwise: *unknown*
> Guiding rule: never break a setup that works today. Pick a better default
> when there is evidence; otherwise keep today's behaviour and warn.
> h3. Acceptance criteria
> * *Scope.* Only community plugins added without {{--version}} or {{--gav}}.
> Built-in {{org.apache.camel}} plugins keep resolving to the CLI version.
> * *Selection.*
> ** List versions with {{resolveAvailableVersions}}, excluding SNAPSHOT and
> qualifier versions.
> ** Walk newest-first, with a capped number of POM reads.
> ** Select the first release whose range (declared, else inferred) contains
> the host CLI version. A SNAPSHOT CLI is compared without {{-SNAPSHOT}};
> {{--camel-version}} is ignored.
> * *Registration.* Resolve the selected jar before changing configuration.
> Store the exact GAV, the range, and its kind (declared/inferred) in the
> plugin entry. Print the selection, e.g. {{Selected forage 1.6.2 for Camel CLI
> 4.22.2 (built for Camel 4.22.2)}}.
> * *No match, newest release declares a range.* Fail (stderr, nonzero exit)
> and leave configuration unchanged. Show the CLI version, the newest release
> per line found during the walk, and commands for a supported pairing.
> * *No match, inferred/unknown data only.* Keep today's behaviour ({{LATEST}})
> and warn, naming the newest release and the Camel version it was built for.
> * *Metadata or POMs unreadable* (network/offline). Keep today's behaviour and
> warn that compatibility could not be checked.
> * *Explicit choices.* {{--version}} and {{--gav}} register exactly what was
> asked, with a warning if the release's range excludes the CLI. They are never
> blocked.
> * *Load time.* Extend the existing {{versionCheck}} step: if a stored range
> excludes the CLI (e.g. after a CLI upgrade), warn and suggest {{camel plugin
> add <name>}}. Use stored data only, with no network call. Entries without a
> stored range, including all existing registrations, are not checked.
> * *4.18 LTS.* Decide whether to backport the known-plugin catalog
> (CAMEL-23491, first released in 4.21.0) together with this, or to document
> {{--gav}} for 4.18. Without the catalog, {{camel plugin add forage --version
> X}} on 4.18 registers {{org.apache.camel:camel-jbang-plugin-forage}}, which
> does not exist.
> * *Docs.* Document the property and the inference in the custom-plugin guide.
> * *Tests.*
> ** declared, inferred and unknown sources
> ** newer and older plugin patches within a line
> ** no match for each kind
> ** explicit {{--version}} / {{--gav}}
> ** built-in plugins unchanged
> ** SNAPSHOT CLI and an offline/unreachable repository
> ** existing registrations, and a CLI upgrade after add
> ** a fixture plugin, to keep the implementation generic
> h3. Expected effect on today's plugins
> ||Plugin / case||Today||With this change||
> |Forage on CLI 4.22.x|LATEST = 1.6.2 (1.7.0 once released)|1.6.2|
> |Forage on CLI 4.23.0|LATEST = 1.6.2, {{camel run}} broken|1.7.0 once
> released|
> |kit on CLI 4.22.x / 4.23.0|LATEST = 0.4.1|0.4.1, unchanged (warning on 4.23)|
> |kit on CLI 4.18.x (if backported)|LATEST = 0.4.1|0.3.1 (built for 4.18.0),
> printed|
> |Built-in plugins|CLI version|unchanged|
> |--version / --gav|as given|as given, plus a warning on a known mismatch|
> |Existing registrations|-|untouched|
> The kit maintainer should be notified before release. If kit 0.4.x supports
> 4.18, declaring {{camel.jbang.plugin.camel-versions}} keeps 0.4.1 selected.
> h3. Evidence
> A containerised compatibility matrix used the official launchers, a clean
> {{user.home}} and a fresh Maven cache. It covered:
> * CLI 4.22.0/4.22.1/4.22.2 x Forage 1.6.0/1.6.1/1.6.2
> * CLI 4.18.3/4.18.5 x Forage 1.4.0/1.4.2
> * CLI 4.22.x/4.23.0 x Forage 1.7.0-SNAPSHOT
> Probes: config read, {{camel run}} / {{camel forage run}} with a JDBC
> datasource, the Shiro example over platform-http, and export to main/Spring
> Boot/Quarkus (plus {{mvn package}} for 4.23.0 x 1.7.0).
> Results:
> * Within each minor line, every patch combination behaved like the exact
> pairing.
> * CLI 4.23.0 x Forage 1.6.2 fails ({{jbang}} runtime).
> Relevant code:
> * {{PluginAdd.java}}, {{PluginHelper.java}}, {{known-plugins.json}} in
> {{dsl/camel-jbang/camel-jbang-core}}
> * {{MavenDownloader}} / {{MavenDownloaderImpl}} in
> {{tooling/camel-tooling-maven}}: add a resolved-POM read next to
> {{resolveAvailableVersions}}
> Related: KaotoIO/forage#533 (Forage 1.7.0: {{jbang}} runtime fix, declared
> range, self-check warning).
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
