How to Contribute

Welcome and thank you for your interest in contributing to Apache Brooklyn! This guide will take you through the process of making contributions to the Apache Brooklyn code base.

TL;DR

Contributor License Agreement

Apache Brooklyn is licensed under the Apache License, Version 2.0. All contributions will be under this license, so please read and understand this license before contributing.

For all but the most trivial patches, we need a Contributor License Agreement for you on file with the Apache Software Foundation. Please read the guide to CLAs to find out how to file a CLA with the Foundation.

Join the Community

If it’s your first contribution or it’s a particularly big or complex contribution, things typically go much more smoothly when they start off with a conversation. Significant changes are normally discussed on the mailing list in any case, sometimes with a feature proposal document.

Visit our Community page to see how to contact Brooklyners via IRC or email.

Create an Issue in Jira

The first step is usually to create or find an issue in Brooklyn’s Jira for your feature request or fix. For small changes this isn’t necessary, but it’s good to see if your change fixes an existing issue anyway.

Pull Request at GitHub

This is our preferred way for contributing code. Our root GitHub repository is located at https://github.com/apache/brooklyn with most of the code in one of the subprojects. You can checkout and PR against just one of the projects listed there. See the README in our root repository for information on subprojects.

Your commit messages must properly describes the changes that have been made and their purpose (here are some guidelines). If your contributions fix a Jira issue, then ensure that you reference the issue (like BROOKLYN-9876) in the commit message.

Create a pull request (PR) in GitHub for the change you’re interested in making. Include a link to the Jira issue (if it has one) in the PR comment as well as the commit message.

Some good references for working with GitHub are below.

Finally, add a comment in the Jira issue with a link to the pull request so we know the code is ready to be reviewed.

The Review Process

The Apache Brooklyn community will review your pull request before it is merged. If we are slow to respond, please feel free to post a reminder to the PR, Jira issue, IRC channel or mailing list – see the Community page to see how to contact us.

During the review process you may be asked to make some changes to your submission. While working through feedback, it can be beneficial to create new commits so the incremental change is obvious. This can also lead to a complex set of commits, and having an atomic change per commit is preferred in the end. Use your best judgement and work with your reviewer as to when you should revise a commit or create a new one.

You may also get automated messages on the pull request from the CI running tests or GitHub determining whether a PR can be merged. Please keep these up to date to aid reviewers.

A pull request is considered ready to be merged once it gets at lease one +1 from a committer. At this point your code will be included in the latest Apache Brooklyn. Congratulations and thank you!

Contributing without using GitHub

If you prefer to not use GitHub, then that is fine - we are also happy to accept patches attached to a Jira issue. Our canonical root repository is located at https://gitbox.apache.org/repos/asf/brooklyn.git with others in brooklyn-*.git; for example:

$ git clone https://gitbox.apache.org/repos/asf/brooklyn-server.git

When producing patches, please use git format-patch or a similar mechanism - this will ensure that you are properly attributed as the author of the patch when a committer merges it. The review process will be as with pull requests, except for comments only appearing on the Jira issue.

Handy Places

If you’ve not done so, you’ll probably want to start by getting the code. Once you’ve done that, you’ll find handy development bookmarks here.