Resources

Mailing Lists

Bug Tracker, IRC, and CI

Contribute

There are many ways you can help make Karaf a better piece of software - please dive in and help!

Try browsing the documentation - if something's 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 ?

If you'd rather have a more gentle introduction to working on the Karaf project, try looking at the test coverage report and help us get it even more green by supplying more test cases to get us closer to 100% coverage.

Report bugs and feature requests

Did you find a bug or want something implemented? Please report an issue in our issue tracker. When creating a bug make sure you document the steps to reproduce the issue and provide all necessary information like OS, versions your use, logs. When creating a feature request document your requirements first. Try to not directly describe the solution.

If you want to dive into development yourself then you can also browse for open issues or features that need to be implemented. Take ownership of an issue and try fix it. Before doing a bigger change describe the concept/design of what you plan to do. If unsure if the design is good or will be accepted discuss it on the dev list.

Provide changes in a pull request

The best way to provide changes is to fork karaf repo on github and provide a pull request with your changes. To make it easy to apply your changes please use the following conventions:
  • Every pull request should have a matching jira issue
  • Do the change in a branch that is named like the jira issue id e.g KARAF-1234. To create this branch you can use:
    git clone http://github.com/apache/karaf
    git fetch --all
    git checkout -b my-branch origin/master
     Don't forget to periodically rebase your branch:
    git pull --rebase
    git push GitHubUser my-branch --force
  • Every commit in the branch should start with the jira issue id like this "[KARAF-123] More details"
  • You can squash your commits into one and force push your branch (not mandatory) using git rebase -i apache/master
  • Test that your change works by adapting or adding tests.
  • Follow the boy scout rule to "Always leave the campground cleaner than you found it."
  • Make sure you do a build before doing a PR. The build has to be successfull:
    mvn clean verify -Prelease -fae -T 1C
  • If your PR has conflicts with the master then rebase the branch. PRs with conflicts are unlikely to be applied
  • Do not change too much in a PR. The smaller the PR the easier it is to apply and the faster it will be done
  • Sometimes PRs get lost. Do not hesitate to ask on the dev list if your PR seems to be ignored

Review pull requests

Anyone can review pull requests but the merge can be done only by a committer.
If you want to review a PR then comment with R:@yourgithubid. This marks that you will do the review and also apply if you are a committer.
When reviewing check if the changes are done in a clean way and are tested with a unit and possibly integration test. Check that the build does not report more test failures than before. If you are not a committer then write a comment if you recommend a merge or not. Provide good instructions for the contributor how to improve his PR if it is not yet ok. Make sure you do a review timely. By commenting that you do a review you kind of block others from applying the change.
NB: Jenkins performs a build for each pull request. You can trigger a new build on a pull request using "retest this please" in a PR comment.

Apply pull requests

This can obviously only be done by a committer. Do the following steps:
  • As one time config, you can rename your git remote and add apache one: git remote add apache https://gitbox.apache.org/repos/asf/karaf.git
     We recommand renaming origin as github:
    git remote rename origin github
     For github remote, add an additional fetch reference, which will cause every pull request to be made available as a remote branch in your workspace.
    git config --local --add remote.github.fetch '+refs/pull/*/head:refs/remotes/github/pr/*' You can confirm your configuration with the following command: git remote -v
    apache https://gitbox.apache.org/repos/asf/karaf.git (fetch)
    apache https://gitbox.apache.org/repos/asf/karaf.git (push)
    github https://github.com/apache/karaf.git (fetch)
    github https://github.com/apache/karaf.git (push)
    username git@github.com:username/karaf.git (fetch)
    username git@github.com:username/karaf.git (push)
  • Checkout the PR:
    git fetch --all git checkout -b pr-xxx github/pr/xxx
  • Review the PR, amend, squash the commits, requesting changes, ... When done, add LGTM comment to approve the PR (or click on the "Approve" button on GitHub):
    git rebase -i apache/master
  • Merge the PR (it automatically closes the PR):
    git fetch --all
    git checkout apache/master
    git merge --no-ff -m "[KARAF-nnnn] This closes #xxx" pr-xxx git push apache HEAD:master
  • Eventually backport commits to bugfix branches using git cherry-pick
  • Make sure you document the fix in jira by adding the fix versions and resolve the jira issue
  • You can delete the PR branch: git branch -D pr-xxx.

Improve the karaf website

The content of the website http://karaf.apache.org is stored in the svn repo karaf site. See the README.md on top level for how to test and publish the website.

Support

If you are experiencing problems using Karaf then please report your problem to our issue tracker. You may also find it useful to discuss your issues with the community on the mailing lists or IRC.

How to get help

Whenever you are reporting a problem please be sure to include as much information as possible; the more we know the more chance of a quicker resolution.
  • which Karaf version you're using
  • what platform and JDK?
  • the particular OSGi container being used - if so what version
  • stack traces generally really help! If in doubt include the whole thing; often exceptions get wrapped in other exceptions and the exception right near the bottom explains the actual error, not the first few lines at the top. It's very easy for us to skim-read past unnecessary parts of a stack trace
  • log output can be useful too; sometimes enabling DEBUG logging can help
  • your code & configuration files are often useful. Be careful not to send us anything of a sensitive nature
  • did it work before, what have you changed to break it?
  • try upgrading to the latest release and see if it's fixed in that release
  • try the latest SNAPSHOT to see if it's fixed in that release
  • search the user mailing list to see if has been discussed before
  • check the issue tracker to see if the issue already have been reported

How to get help faster

We may be able to help you much more quickly if you try the following
  • provide us with a JUnit test case that demonstrates your issue. e.g. if you think you've found a bug, can you create a test case to demonstrate the bug ?
  • submit a patch fixing the bug! (we also buy you beer when we meet you if you submit bug fixes :) )
  • for memory leak or performance related issues, if you can run a profiler on your test case and attach the output as a file (or zipped file if it's huge) to the JIRA we can normally fix things much quickly. E.g. you could run jmap/jhat, JProfiler or YourKit on your code and send us the output. To find memory leaks it's quicker to resolve if you can tell us what classes are taking up all of the RAM; we can normally figure out what's wrong from that

Commercial Support

Apache Karaf is a widely used project. As such, several companies have built products and services around Karaf. Companies are definitely encouraged to update this page directly or send a mail to the Karaf PMC with a description of your offerings and we can update the page. The products and services listed on this page are provided for information use only to our users. The Karaf PMC does not endorse or recommend any of the products or services on this page.
  • Codecentric provides consulting and training for Apache Karaf and related technologies e.g. Apache Camel, Apache ActiveMQ and CXF for the DACH region.
  • Savior Technologies, Inc contributes and commits to the Apache Karaf project, while providing enterprise consulting, training and support for Karaf and a host of other Apache service containers. Savoir can provide best practice mentoring for developing with Karaf, as well as architectural/design reviews, troubleshooting and SOA infrastructure implementations.
  • Talend uses and contributes on Apache Karaf. The Talend Runtime is based on Karaf. Talend has a dedicated team for the Apache projects. This team provides consulting, training, specific development, and support on Karaf (and other Apache projects).

Team

Name ID PMC Organisation
David Bosschaert davidb
Ioannis Canellos iocanel JBoss
Hiram Chirino chirino JBoss
Chris Custine ccustine
Andrea Cosentino acosentino RedHat
Lukasz Dywicki
Freeman Fang ffang JBoss
Jarek Gawor jgawor IBM
Christoph Gritschenberger christophg
Jamie Goodyear jgoodyear Savoir Technologies
David Jencks djencks IBM
Alex Karasulu akarasulu
Charles Moulliard cmoulliard JBoss
Achim Nierbeck anierbeck Codecentric
Guillaume Nodet gnodet JBoss
Jean-Baptiste Onofre jbonofre Talend
Andreas Pieber pieber
James Strachan jstrachan JBoss
Christian Schneider cschneider Talend
Adrian Trenaman
Gert Vanthienen gertv JBoss
Brian Topping btopping
Heath Kesler hkesler Savoir Technologies