docs/modules/ROOT/pages/contributor-guide/create-new-extension.adoc

[[create-a-new-extension]]
= Create a new extension
:page-aliases: create-new-extension.adoc

1. You should know xref:contributor-guide/index.adoc#how-to-build[how to build].

2. Go through the https://quarkus.io/guides/extension-authors-guide[Quarkus extension author's guide] to get an idea of
   what is expected from you.

3. Make sure that nobody else works on the same extension already by searching through the
   https://github.com/apache/camel-quarkus/issues[GitHub issues].

4. Let others know that you work on the given extension by either creating a
   https://github.com/apache/camel-quarkus/issues/new[new issue] or asking to assign an existing one to you.

5. Scaffold the necessary Maven modules using `quarkus-maven-plugin`. As an example let's add a new extension for
   supporting an imaginary Camel component `foo-abc`:
+
[source,shell]
----
$ cd camel-quarkus
$ mvn cq:create -N -Dcq.artifactIdBase=foo-abc
----
+
where:
+
* `foo-abc` is the unique part of the new extension's `artifactId` without the `camel-quarkus-` prefix
+
The above sequence of commands does the following:
* It creates three new Maven modules under the `extensions` directory: `camel-quarkus-foo-abc-parent`, `camel-quarkus-foo-abc`
  (a.k.a. the runtime module) and `camel-quarkus-foo-abc-deployment`.
* These three modules are linked where necessary:
** `camel-quarkus-foo-abc-parent` is added to the `<modules>` of `camel-quarkus-extensions`
** `camel-quarkus-foo-abc` is added to the `<dependencyManagement>` of the runtime BOM (Bill of Materials) `poms/bom/pom.xml`
** `camel-quarkus-foo-abc-deployment` is added to the `<dependencyManagement>` of the deployment BOM (Bill of Materials) `poms/bom-deployment/pom.xml`
* It creates a basic `FooAbcProcessor` class in the deployment module.
* It also creates a stub of an integration test module under `integration-tests/foo-abc`.
+
6. Add the extension name to the right category in  `tooling/scripts/test-categories.yaml` file.
+
Compilation performed immediately after generating the modules should pass flawlessly but running the tests will fail
because the test project needs to get finished. You need to build `poms/bom` and `poms/bom-deployment` one time first.

7. Review the generated
   `extensions/foo-abc/runtime/src/main/resources/META-INF/quarkus-extension.yaml` file.
+
The
`description` comes from Camel Catalog. If it looks improper or too long due to concatenation of multiple
component descriptions, you may override it by setting an explicit `<description>` in the runtime `pom.xml`
of your new extension. If you think the value coming from Camel Catalog should be changed, please
https://issues.apache.org/jira/secure/CreateIssue!default.jspa[file a new Camel issue] and ask to fix the metadata
for the given Camel component.
+
If there is some important keyword missing in both the `name` and `description` through which your new extension
should definitely be findable on https://{link-quarkus-code-generator}[{link-quarkus-code-generator}], consider setting
`<quarkus.metadata.keywords>` property in your runtime `pom.xml`.
+
Run `mvn -N cq:update-quarkus-metadata` from the source tree's root directory to re-generate the
`quarkus-extension.yaml` file.
+
Check the xref:contributor-guide/extension-metadata.adoc[Extension metadata] page for more details about the `quarkus-extension.yaml` file

8. Review the dependencies in the generated runtime and deployment modules. In case the given library is supported by
   Quarkus, you may want to add a dependency on the corresponding Quarkus extension.

9. Complete the integration test module under `integration-tests/foo-abc`,
   following the xref:contributor-guide/extension-testing.adoc[Extension testing] guide.
   Make sure the tests are passing both in the JVM mode (`mvn test`) and in the native mode (`mvn verify -Pnative`).

10. In case of problems, consult the https://quarkus.io/guides/extension-authors-guide[Quarkus extension author's guide],
   ask for help in the given GitHub issue or via https://camel.zulipchat.com[Camel Quarkus chat].

11. Read the xref:contributor-guide/extension-documentation.adoc[Extension documentation] page and add `configuration.adoc`,
   `usage.adoc`, etc. in `src/main/doc` directory of the runtime module if necessary.
+
   After completing the extension documentation, run `mvn clean install -DskipTests`
   from the root of the source tree to add your extension to the autogenerated list of extensions.

12. Before sending a pull request, please make sure you have run the following Maven command from the project root folder:
+
[source,shell]
----
$ mvn process-resources -Pformat
----
+
The above command will perform the following tasks:
+
* Add license headers to the new files
* Re-generate the list of extensions and the Camel Quarkus Catalog
* Sort elements in various POM files properly
+
Review the result visually.

13. Please squash your commits before sending a pull request.

Good luck!