Important changes coming in Quarkus 3.14

[gsmet]

Hi @quarkiverse/quarkiverse-members ,

For Quarkus 3.14, a new extension annotation processor has been developed.

This will probably require some changes in your extension once you update to 3.14.

I have described the changes in details in the 3.14 migration guide: https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.14#for-extension-developers .

If you have any questions or encounter any issues, you can ping me anytime, I'm here to help.

Thanks.

--
Guillaume

[gastaldi]

@gsmet are those changes automatically applied when a new extension is created using quarkus create extension?

[gsmet]

Not at the moment, but I created quarkusio/quarkus#42401 yesterday and I will fix it before CR1.

[turing85]

Hi! Thanks Guillaume for the nice guide! in the migration guide, section "publishing the config documentation" [1], it may be worth mentioning that the change only affects the "docs" submodule. If one takes a close look at the patch, then one can see this. But I was confused for a minute. WDYT? [1]: https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.14#publishing-the-config-documentation

…

On 08.08.24 20:23, Guillaume Smet wrote: Hi @quarkiverse/quarkiverse-members <https://github.com/orgs/quarkiverse/teams/quarkiverse-members> , For Quarkus 3.14, a new extension annotation processor has been developed. This will probably require some changes in your extension once you update to 3.14. I have described the changes in details in the 3.14 migration guide: https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.14#for-extension-developers . If you have any questions or encounter any issues, you can ping me anytime, I'm here to help. Thanks. -- Guillaume — Reply to this email directly, view it on GitHub <#228>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHYTGL33VNDULFOVRYLQPSLZQOZRJAVCNFSM6AAAAABMHARMCOVHI2DSMVQWIX3LMV43ERDJONRXK43TNFXW4OZXGAZDMOJVGI>. You are receiving this because you are on a team that was mentioned.Message ID: ***@***.***>

[gsmet]

I added some clarifications.

[ppalaga]

Is there a Quarkiverse extension repo, where the migration was done already?

[maxandersen]

@ppalaga can you remind me what it is you need changing in the output ? its not good IMO if extension starts diverging on this as we are also heading towards doing similar to what camel does of generating artifacts IDE's uses. so lets make sure we get the needs captured.

[gsmet]

Same as @maxandersen . Except if you have oddly specific requirements, it would be better to improve the centralized plugin, rather than having people maintaining specific machinery.

And if you have oddly specific requirements, probably a good idea to discuss it to see if we can make the new stuff configurable for you.

We used to be very shy of updating this code as it was hard to evolved and very brittle. The new code is a lot more clean and flexible and the model generation is split from the output generation so we should be able to tweak the output a lot more easily.

[ppalaga]

There are several issues with the current state of the GenerateAsciidocMojo and the annotation processor. Some of them are easy to solve within the current design, some of them are harder:

• Change the qute template so that there is less unused space - see Figure out how to better present config options  antora-ui-quarkiverse#56 and see how we already render in Quarkus CXF: https://docs.quarkiverse.io/quarkus-cxf/dev/reference/extensions/quarkus-cxf.html#quarkus-cxf_quarkus-cxf-codegen-wsdl2java-includes
• Render @since version if available in JavaDoc. The metadata is correctly passed to yaml. Again, only the Qute template would have to get adjusted. This how we currently render it in Quarkus CXF:
  
• Camel Antora UI required some special AsciiDoc markup, but I do not remember the details. Being able to override the default templates would perhaps solve the issue.
• For Camel Quarkus and Quarkus CXF, we have custom plugins in place, that assemble the whole extension reference page (each extension has one) - see e.g. https://docs.quarkiverse.io/quarkus-cxf/dev/reference/extensions/quarkus-cxf-rt-features-metrics.html or https://camel.apache.org/camel-quarkus/3.8.x/reference/extensions/aws2-s3.html Note that in those pages the config section is optional (because some extensions do not have Quarkus config). The other sections are generated from extension metadata and some adoc chunks stored in src/adoc, such as usage.adoc, limitations.adoc, etc. We could in theory include the config section generated by GenerateAsciidocMojo, which we also did in the past, but that kind of solution was complex and hard to maintain and debug. Therefore we switched to our own custom plugins that assemble the whole reference page. I wonder if Quarkus team would be ready to widen the scope of the plugin to output the whole reference page?
• Our current setup does not require to rebuild the docs module when something in an extension was changed. It is enough to rebuild the extension. The current Quarkus solution requires rebuilding the docs module. I wonder if you have some CI in place that amends the generated changes when a dev forgets to rebuild the docs module?

[gsmet]

I don't see anything that would be problematic with the new design.

Maybe let's have this discussion in the Quarkus tracker instead of here, given all the Quarkiverse members get notified?

[gsmet]

I started a discussion here to address your feedback: quarkusio/quarkus#42476

[turing85]

Speaking of which: is 2024-08-14 still the ETA for 3.14.0? And can we expect a "CR1" before the final release?

…

On 08.08.24 22:17, George Gastaldi wrote: I think 3.14 needs to be released for that to happen? — Reply to this email directly, view it on GitHub <#228 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHYTGL3TFSTQLHXN72VJQJLZQPG3ZAVCNFSM6AAAAABMHARMCOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTAMRXHE2TEMY>. You are receiving this because you are on a team that was mentioned.Message ID: ***@***.***>

[gsmet]

https://github.com/quarkusio/quarkus/wiki/Release-Planning#314-proposal

[metacosm]

I think it would be interesting to add the @ConfigMapping compatibility level with different Quarkus version because the approach chosen by developers might depend on their backward compatibility constraints with older Quarkus versions. In my case, for example, I'm wondering if it's better to rewrite the configuration sub-system using only @ConfigMapping or go the mixed-approach way.

[gsmet]

What do you mean by mixed approach?

Historically, for extensions, you were doing:

@ConfigRoot(name = "github-app", phase = ConfigPhase.RUN_TIME)
public class GitHubAppRuntimeConfig {

When switching to the new and improved @ConfigMapping for extensions, you need to use:

@ConfigRoot(phase = ConfigPhase.RUN_TIME)
@ConfigMapping(prefix = "quarkus.github-app")
public interface GitHubAppRuntimeConfig {

3.8 supports @ConfigMapping for extensions but we fixed some bugs in corner cases along the way so if you have a complex config, you might have some issues.

[michael-simons]

There is no such thing as "Mixed approach" as far as I understand it @metacosm
You need both annotations.
And when you use the small rye one (@ConfigMapping), the annotation processor ensures you cannot use name and or prefix of @ConfigRoot anymore. However, the phases of @ConfigRoot are still required.

[gsmet]

If some of you are considering moving to @ConfigMapping (it's not mandatory but it can be a good opportunity to do it), you can have a look at what I did here: https://github.com/quarkiverse/quarkus-github-app/pull/645/files#diff-e57f34825aa8598a1397b16e4cf50b3a67672d287ea6e4946203ded8e5f5d484 .

One very important thing is that the prefix has to be moved to the @ConfigMapping annotation and that you need to prepend it with quarkus..

[michael-simons]

What's the point of the change? Couldn't find it in the links shared here.
As 3rd party contributor, the move feels pointless. Care to elaborate now using Interfaces and proxies?

[michael-simons]

using legacy config roots

That is the key point of your statement. They will not be legacy forever, they will vanish at some point in the future idk yet. I have to take care of this either way. I could ignore this by mitigating right now, or bite it and migrate now. I would be annoyed either way, but if Quarkus changed it on a major, and yes, carrying the legacy around for one major, less so. :)

[gsmet]

They won't but they have been legacy for quite a long time. What I want to emphasize is that it's orthogonal and I really don't have an issue with people going the easy way of adding the compiler argument - that's why I documented this approach. We won't break it any time soon - especially since the core is still full of legacy config roots :).

[michael-simons]

That's good to know, but than I hope for sure that they don't keep standing in the way of other initiatives then :)

[radcortez]

I personally find the choice of targeting JDK 11 the most irritating thing, records would have been perfect, but than I don't follow the Jakarta politics about which version targets which other that closely, so I guess there are reasons.

Well yes, we had to go for the minimum supported version. While records could be supported, we had to come up with something for pre record support.

[radcortez]

@radcortez There's that point that primitive values have already defaults and I read it like you think that it's a con argument. I would think it's pro, as most developers know the primitives default values, they are the same everywhere, and I found it pretty convenient.

Con, in a sense, you would require extra specifications to detail how things should behave. Nothing is wrong with that piece, but the group understood that the configuration may be set by an operator, who may not be a developer and not necessarily know the differences between primitives and wrapper types.

[michael-simons]

What about Quarkus unit tests, I have

	@RegisterExtension
	static final QuarkusUnitTest unitTest = new QuarkusUnitTest()
		.setArchiveProducer(() -> ShrinkWrap.create(JavaArchive.class)
			.addClass(SomeClass.class)
			.addClass(SomeOtherClass.class))
		.overrideConfigKey("org.neo4j.ogm.base-packages", "org.neo4j.ogm.quarkus.test.domain")
		.overrideConfigKey("org.neo4j.ogm.use-native-types", "true")
		.overrideConfigKey("org.neo4j.ogm.use-strict-querying", "true")
		.overrideConfigKey("org.neo4j.ogm.database", "aDatabase");

and now that tests yells at me

java.lang.RuntimeException: io.smallrye.config.ConfigValidationException: Configuration validation failed:
	SRCFG00050: org.neo4j.ogm.use-native-types in PropertiesConfigSource[source=file:/tempfile/application.properties]:6 does not map to any root

with @ConfigMapping? Can't find a hint on that.

[radcortez]

Ok, let me check. I may have forgotten something.

[radcortez]

It works. Issue is in the mapping prefix. Was quarkus.neo4j.ogm, but it needs to be org.neo4j.ogm, since this is the config namespace you are using in the test, unless you also want to migrate that :)

neo4j/neo4j-ogm-quarkus#372

[michael-simons]

That's brilliant, thank you so much @radcortez This is obviously my fault (Was trying things out, because those kinda migrations / customisations are not documented as a whole).

See, and that's my reason why I thing that discussions belongs here, @gsmet

I was initially pulled in into this thread with reason of the new annotation processor.
Ofc I can do Tickets somewhere else and I have a proven track record of doing this (and fixing them my own many times). But here we already had a discussion, and from my PoV it was the exact right spot.
For sure, my implied feedback is not positive, but take it nevertheless sent with good intention. The quarkus team makes a move, that requires a lot of changes either by following along, or swallowing some changes in config with unnecessary consequences (the warning sent to the compiler that can't be disabled), and maybe not everyone can understand or see the reason behind it immediately.
Also take note that I not once asked to change anything, but just trying to figure out how to migrate proper.
Thanks.

[gastaldi]

See, and that's my reason why I thing that discussions belongs here, @gastaldi

I think you mean @gsmet ? Anyway, glad it got all sorted out 😉

[michael-simons]

D'oh. Sorry.

[michael-simons]

For people coming after me:

Here's the commit in an application with a straight forward migration to the new config processor:

quarkiverse/quarkus-neo4j@585d499

And here's an another extension that does not live in the Quarkiverse and hence does not use the quarkus. prefix in its configuration properties. It requires a Smallrye config customizer ignore the config patterns under the prefix, the same way it does for properties prefixed with quarkus.*.
Take note that the pattern must end in whatever.** (two asterisks):

neo4j/neo4j-ogm-quarkus@fe86876

Thanks a lot for helping me out with the latter, @radcortez I would not have found out this alone.

[gsmet]

Sorry but I will have to reiterate: what you point out is a migration to the new extension annotation processor + a migration to @ConfigMapping.

The second part is not necessary and is orthogonal to what is required to migrate to 3.14.

Let’s not create confusion here. Thanks.

[michael-simons]

Your change in Quarkus requires one of two actions. One is going down the deprecation path, one is the migration. Both have consequences, both are none trivial. Thanks for devaluing my positive comment that describes how to do one of them.

I’m unsubscribed now from this and frankly, quite disappointed. Lesson learned: feedback is not appreciated here.