Working Group Proposal: Structuring Quarkus Extensions

[cescoffier]

Objective

The main objective of this working group is to define and formalize conventions for structuring Quarkus extensions, including module and package layout, public/private separation, and supporting tooling. It is related to the WG - Restructuring Quarkus Core Repository proposal.

The Problem

The current Quarkus extension structure, primarily using runtime and deployment modules, lacks clarity and consistency when separating public and private APIs and build items. Over time, as the number of extensions in the Quarkus core repository has grown (170+), this has resulted in:

• Inconsistent use and visibility of build items.
• Difficulty in maintaining and evolving the extensions.
• Unclear guidance for contributors and extension authors.
• Integration tests are being disconnected from the extension code, making development and debugging harder.

The Proposed Solution

This working group will define a set of structural conventions for Quarkus extensions, by introducing optional spi (for runtime) and deployment-spi (for deployment) modules. It will also:

• Recommend standardized package naming conventions to separate public and internal APIs clearly.
• Define Maven pom.xml layout and dependency patterns.
• Define the extension metadata layout
• Document the intended use and separation of runtime, deployment, spi, and deployment-spi artifacts and their dependencies between them
• Create a supporting tool (or set of tools) to detect and report compliance with the new structure (for tracking purposes only).
• Identify candidate extensions that would benefit from restructuring and apply the new structure to a small, representative set (1–10 extensions). The idea is to work on these extensions to identify caveats and breaking changes.
• Publish the results and conventions in the form of an ADR.

This working group does not aim to restructure all extensions in Quarkus Core or Quarkiverse. That will be the responsibility of follow-up working groups.

Definition of Done

This working group will be considered complete when:

• An ADR describing the new extension structure conventions is published.
• A tool or script exists to analyze extension structure and track compliance.
• A list of extensions needing restructuring is compiled.
• 1 to 10 core extensions restructured according to the new conventions.
• Documentation and guidance for extension authors are published.

Scope of Work

In Scope:

• Defining conventions for module (runtime, deployment, spi, deployment-spi) and package structure
• Dependency and visibility guidelines
• Creating a compliance checker tool
• Selecting and restructuring a few representative extensions (this work has already started with the TLS registry restructuration)
• Documentation and communication of conventions

Out of Scope:

• Restructuring the entire core repository (covered in a follow-up working group)
• Restructuring all Quarkus or Quarkiverse extensions

Points of Contact:

• Clement Escoffier and Guillaume Smet

[cescoffier]

\CC @gsmet @geoand

[dmlloyd]

It would be very helpful to include JPMS module name in the conventions. It does not make sense to mandate full modularization at this time, however extensions could very easily add an Automatic-Module-Name when adopting these conventions.

The recommended module name will generally be derived from the package name/structure so it should be straightforward to include this now, and it will save us from headaches later.