docs/modules/ROOT/pages/contributor-guide.adoc

[[contributor-guide]]
= Contributor guide

[[prerequisites]]
== Prerequisites

* `git`
* `docker` for the native mode, see https://quarkus.io/guides/building-native-image-guide[Building a native executable] section of the Quarkus documentation.
* Java 8
* Maven 3.5.3+ (unless you use the Maven Wrapper, a.k.a. `mvnw` available in the source tree).

[[how-to-build]]
== How to build

Checkout the code

[source,shell]
----
git clone https://github.com/apache/camel-quarkus.git
cd camel-quarkus
----

A fast build without tests:

[source,shell]
----
mvn clean install -DskipTests
----

A build with integration tests in the JVM mode only:

[source,shell]
----
mvn clean install
----

A build with integration tests in both the JVM mode and the native mode:

[source,shell]
----
mvn clean install -Dnative
----


== Create a new extension

1. You should know link:#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
   what is expecting 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`:
+
[source,shell]
----
cd camel-quarkus
cd extensions
mvn quarkus:create-extension -N \
    -Dquarkus.artifactIdBase=foo \
    -Dquarkus.nameBase="Foo"
----
+
where:
+
* `foo` is the unique part of the new extension's `artifactId` without the `camel-quarkus-` prefix
* `Foo` is the unique part of the artifact name without the `Camel Quarkus :: ` prefix
+
The `artifactId` and artifact `name` prefixes and suffixes are added automatically by the plugin.
+
The above sequence of commands does the following:
* It creates three new Maven modules under the `extensions` directory: `camel-quarkus-foo-parent`, `camel-quarkus-foo`
  (a.k.a. the runtime module) and `camel-quarkus-foo-deployment`.
* These three modules are linked where necessary:
** `camel-quarkus-foo-parent` is added to the `<modules>` of `camel-quarkus-extensions`
** `camel-quarkus-foo` is added to the `<dependencyManagement>` of the runtime BOM (Bill of Materials) `poms/bom/pom.xml`
** `camel-quarkus-foo-deployment` is added to the `<dependencyManagement>` of the deployment BOM (Bill of Materials) `poms/bom-deployment/pom.xml`
* It creates a basic `FooProcessor` class in the deployment module.
* It also creates a stub of an integration test module under `integration-tests/foo`.
+
A compilation performed immediately after generating the modules should pass flawlessly but running the tests will fail
because the test project needs to get finished.
+
TIP: The `nameBase` parameter of the mojo is optional. If you do not specify it on the command line, the plugin will
derive it from `artifactIdBase` by replacing dashes with spaces and uppercasing each token. So you may consider omitting
explicit `nameBase` in some cases.

6. Complete the extension by adding dependencies to the runtime module. You probably want to add a dependency on
   on the given Camel component - in our case `org.apache.camel:camel-foo`.

7. Complete the integration test module under `integration-tests/foo`. Make sure you test both the consumer and the
   producer of the component (if the component supports both). Make sure the tests are passing both in the JVM mode
   (`mvn test`) and in the native mode (`mvn verify -Dnative`).

8. 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://gitter.im/apache/camel-quarkus[Camel Quarkus chat].

Good luck!