Adding extensions to the Quarkus ecosystem

Adding extensions to the Quarkus ecosystem

This document describes how to add an extension to the ecosystem.

Quarkus has two notions.

The platform

A set of extensions known to work together, using the same version for shared dependencies and released in coordination.

The universe

All extensions ever made for Quarkus. They might not work with one another (e.g. conflicting dependencies or depending on different versions of Quarkus core).

The platform

When you hear the news of a new Quarkus release in our blog, this is the Quarkus platform. The platform is opinionated to address both Kubernetes Native Java and developer joy.

Kubernetes Native Java

It must be a cohesive platform which is easy to use.
It must encourage cloud native patterns or at least not go against it.
It must consume low memory and compile to native.
…​

Developer Joy

It must be a cohesive platform which is easy to use.
For core technologies, we avoid duplications to limit end user mental overhead and work for extension writers (less integration points to consider).
We make strong setting choices to simplify the platform.
Apps must refresh fast in Live Coding mode.
…​

To join the platform, an extension should follow the philosophy above. The maintainer of the extension, must also commit to long term maintenance and timely updates if a change in Quarkus core (or other extensions) break the extension. The objective is to guarantee to Quarkus users a set of extensions that are here to stay and don’t drop from one version to the next.

To help, we have several mechanisms in place. We offer a GitHub Actions template so that you can run your extension on top of Quarkus master and be notified of any breaking change. We also run every day the whole Quarkus platform on Quarkus core master to verify on any breaking change. As extension writer, you publish a set of tests you expect Quarkus Platform to run.

With these machanism, extension maintainers, you can be notified of a breakage change early.

Warning

TODO: Make Georgios review the statements above and add relevant links

Note

Quarkus no longer accepts Quarkus extensions in https://github.com/quarkusio/quarkus The maintenance of a growing number of extensions in a single place was not trivial. And we want to favor a decentralized model (release cycle independence, multiple ownership etc). Instead, just release the extension on GitHub in your user space or organisation space. Exceptions might be considered to include new simple extensions when there is a significant benefit to have it in the platform, such as when other existing platform extensions needing to depend on it.

Warning

TODO: Do we ask not to use io.quarkus as package name nor quarkus-* as prefix for the extension artifact id?

Process to join the platform

Please send an email to the quarkus-dev mailing list announcing your extension. The community will guide you through options.

As of 2020-05-03, only extensions in the platform are visible and listed on https://code.quarkus.io and the Quarkus tooling. So our process will be to add the extension to the platform with the following approach. If the maintainer:

• has a good test suite

• commits to the long term maintenance and timely release requirements

and if the extension follows the Quarkus platform philosophy, we can add the extension to the platform.

As part of the maturation process, We will add a experimental or preview flag to the extension (see extension status) until the maintainer has executed on its commitment.

The universe

Some Quarkus community members are working on the ability to discover and list all extensions on https://code.quarkus.io and the Quarkus tooling. When this is ready, all extensions whether in the platform or outside will be easily discoverable by users.

In the mean time, an extension is just a dependency. Users can directly add the extension GAV to their Maven pom.xml or Gradle build files.