Contributing to Apache Camel
First of all, thank you for having an interest in contributing to Apache Camel.
Here are some guidelines on how to best approach the Apache Camel community and how to best apply yourself.
There are many ways you can help make Camel better - please dive in and help!
Try surf the documentation - if some things are confusing or not clear, let us know.
Download the code & try it out and see what you think.
Browse the source code. Got an itch to scratch, want to tune some operation or add some feature?
Want to do some hacking on Camel? Try surfing our issue tracker for open issues or features that need to be implemented. Take ownership of an issue and try to fix it.
Leave a comment on the issue to let us know you are working on it and add yourself as a watcher to get informed about all modifications.
Identify areas you can contribute first. You don’t have to be an expert in an area, the Apache Camel developers are available to offer help and guidance.
Introduce yourself on the developer’s mailing list (see below), tell us what area of work or problem you wish to address in Camel. Create a draft of your solution, this can be simple 1-2 sentences on the change you wish to make. Try to be as specific as you can: include a short description of your intent, what you tried and what didn’t work, or what you need help with. The best way of approaching the developers is by describing what you would like to work on and asking specific questions on how to get started. We’ll do our best to guide you and help you make your contribution.
We also participate in Google Summer of Code and Outreachy programs, for information about those look at those program websites. If you wish to participate in either of those follow the guidelines and schedule set by those programs. If you are unsure please reach out via official communication channels of those programs, or ask on the developer’s mailing list for help.
Apache Camel is an Apache Software Foundation project, all communication is done in the open on the project mailing lists. You can read more on the reasoning behind this to get a better understanding of this.
All communication is subject to the ASF Code of Conduct.
There are various ways of communicating with the Camel community.
For questions and guidance around contributing subscribe to the developer’s mailing list by sending an e-mail to email@example.com.
We can also be reached on the Zulip chat at https://camel.zulipchat.com.
After you’re ready to contribute create a Pull request to one of the Camel projects you can find under the Apache organization on GitHub.
Expect that your Pull request will receive a review and that you will need to respond and correspond to that via comments at GitHub.
Make sure you followed the steps and guidelines outlined in this document. For bigger changes, make sure that you have discussed on the developer’s mailing list or in the Jira issue tracker before hand. We love receiving contributions, to get the best response make sure that the reasoning behind the contribution you wish to make is clear: outline the problem and explain your solution for it.
Be mindful of the source checks, formatting and the structure of the git commit message we abide by. This will help you in getting your contribution accepted. Outline any changes you made but are unaware or unsure of any consequences or side effects.
Stay engaged, follow and respond to comments or questions you might be asked.
Documentation is massively important to help users make the most of Apache Camel and it’s probably the area that needs the most help! So if you are interested in helping the documentation effort; whether it’s just to fix a page here or there, correct a link or even write a tutorial or improve what documentation is already there please do dive in and help! We moved the documentation into the code (AsciiDoc). We are not using the wiki system anymore.
To edit the documentation:
It’s easy as opening a Pull Request
You’ll find on each component under src/main/docs an .adoc file
This file contains a static part and a dynamically generated part: the former can be edited directly in the .adoc file, while the latter needs your intervention on the javadoc
Once you modify the javadoc, you’ll need to rebuild the component and the .adoc will be automatically updated
Create a commit and raise a Pull Request
If you want to add more documentation check for .adoc in codebase
Please raise a new issue on our JIRA issue tracker. This way we’ll know when it’s really fixed and we can ensure that the problem stays fixed in future releases. Please describe the bug/issue clearly, and add pictures/screenshots if necessary. If you can create a JUnit test case then your issue is more likely to be resolved quicker. e.g. take a look at some of the existing unit tests cases
We recommend to work on the code from github.
git clone https://github.com/apache/camel.git cd camel
Build the project (fast build).
mvn clean install -Pfastinstall
If you intend to work on the code and provide patches and other work you want to submit to the Apache Camel project, then you can fork the project on github and work on your own fork. The custom work you do should be done on branches you create, which can then be committed and pushed upstream, and then submitted to Apache Camel as PRs (pull requests). You can find many resources online how to work on github projects and how to submit work to these projects.
If you aren’t able to build component after adding some new URI parameters due to
Empty doc for option: [OPTION], parent options: <null> please make sure that you either added properly javadoc for get/set method or description in
If you need to implement tests for your changes, you will probably need to handle 3 separate things: simulate the infrastructure required for the test (ie.: JMS brokers, Kafka, etc), the code changes and the test logic itself. Naturally, there is no rule of thumb for how the code changes and test logic should be. However, in regard to simulating the test infrastructure, there is a growing library of reusable components that can be helpful. These components are locate in the test-infra module and provide support for simulating message brokers, cloud environments, databases and much more.
Using these components is usually as simple as registering them as JUnit 5 extensions:
@RegisterExtension static NatsService service = NatsServiceFactory.createService();
Then, you can access the service by using the methods and properties provided by the services. This varies according to each service.
If you need to implement a new test infra service, check the readme on the test-infra module for additional details.
Apache Camel source code is using a coding style/format which can be checked whether is complying using the checkstyle plugin. To enable source style checking with checkstyle, build Camel with the -Psourcecheck parameter
mvn clean install -Psourcecheck
Please remember to run this check on your code changes before submitting a patch or github PR. You do not need to run this against the entire project, but for example in the modules you work on. Lets say you do some code changes in the camel-ftp component, then you can run the check from within this directory:
cd camel-ftp mvn clean install -Psourcecheck
Camel-Karaf lives now in his own repository, so to verify a Karaf feature you’ll need to fork the following repository.
To check a new Karaf feature or an existing one you should run a verification on the features.xml file. You’ll need to follow these steps: First thing to be done is running a full build of Camel. Then
cd platform/karaf/features/ mvn clean install
If you modified a component/dataformat or updated a dependency in the main camel repository, you’ll first need to build the main camel locally and then run a full build of camel-karaf.
If you are an Apache Camel committer then clone the ASF git repo at
git clone https://gitbox.apache.org/repos/asf/camel.git cd camel
git clone https://github.com/apache/camel.git cd camel
Build the project (without testing).
mvn clean install -Dtest=false
PS: You might need to build multiple times (if you get a build error) because sometimes maven fails to download all the files. Then import the projects into your workspace.
We recommend you create patches as github PRs which is much easier for us to accept and work with. You do this as any other github project, where you can fork the project, and create a branch where you work on the code, and then commit and push that code to your fork. Then navigate to the Apache Camel github webpage, and you will see that github in the top of the page has a wizard to send your recent work as a PR (pull request).
There is also a Git repository at Github which you could fork. Then you submit patches as any other github project - eg work on a new feature branch and send a pull request. One of the committers then needs to accept your pull request to bring the code to the ASF codebase. After the code has been included into the ASF codebase, you need to close the pull request because we can’t do that…
When providing code patches then please include the Camel JIRA ticket number in the commit messages. We favor using the syntax:
CAMEL-9999: Some message goes here
We gladly accept patches if you can find ways to improve, tune or fix Camel in some way.
We recommend using github PRs instead of manual patch files. Especially for bigger patches.
Most IDEs can create nice patches now very easily. e.g. in Eclipse just right click on a file/directory and select Team -> Create Patch. Then just save the patch as a file and attach it to the corresponding issue on our JIRA issue tracker. If you’re a command line person try the following to create the patch
diff -u Main.java.orig Main.java >> patchfile.txt
git diff --no-prefix > patchfile.txt
The easiest way to submit a patch is to
create a new JIRA issue (you will need to register),
attach the patch or tarball as an attachment (if you create a patch file, but we recommend using github PRs)
tick the Patch Attached button on the issue We prefer patches has unit tests as well and that these unit tests have proper assertions as well, so remember to replace your system.out or logging with an assertion instead!
Before you can raise an issue in the issue tracker you need to register with it. This is quick & painless.