-
Notifications
You must be signed in to change notification settings - Fork 262
How to contribute
The Kite SDK is an open source project dedicated to making developers building Apache Hadoop-based applications more productive. We enthusiastically encourage new contributions from people of all skill levels. Contributions are not limited to code, we'd love it if you can help out with: code, build system enhancements, documentation, examples, supporting tools, or anything else you think would benefit our users. In order to make the contribution process as painless as possible, we've established a few guidelines, as well as even fewer hard rules that we ask you to follow.
Join the cdk-dev group for discussion of Kite development.
In order to accept any contribution, the contributor must complete and return a Contributor License Agreement, or CLA. Separate CLAs exist for individuals (an individual contributor license agreement, or ICLA) and corporations (a CCLA). The CLA grants a copyright and patent license to Cloudera, and users of the software, states that you are legally entitled to grant such a license, as well as other important stuff. See the Cloudera ICLA and Cloudera CCLA files included with this software for all of the details.
Completed CLAs may be emailed to cla@cloudera.com, faxed to 1-888-789-1488, or snail mailed to Cloudera's headquarters:
Cloudera, Inc.
Attn: Ryan Blue!
1001 Page Mill Road, Building 2
Palo Alto, CA 94304
Kite uses JIRA to track bugs, feature requests, documentation enhancements, and any other task related to the project. In order to submit issues, you must first create an account on our tracker. To create an account, simply fill out and submit the sign up form. The only prerequisite is an e-mail address. After you sign up, you'll be asked to confirm your e-mail address by clicking on a link sent to your inbox.
One of the most valuable forms of contribution is to submit new issues. Issues can include bug reports, feature requests, documentation suggestions, or other project related tasks. You don't need any special background to submit an issue. In particular, we love it when new people find bugs or have feature requests. Issues can be submitted to the Kite SDK Issue Tracker. From anywhere on the issue tracker click the Create Issue link. If it's not already selected, be sure to set the project to Kite SDK.
Most issues will be either a Bug, New Feature, or Improvement. But don't worry too much about which issue type to use. We can always update it later.
If you'd like to work on an issue you submitted, that's great! However, some folks may like to get involved before they've found a bug or have a specific feature request. To try and make it easier, we curate a list of newbie issues that we think will be accessible to new comers. You should, however, not feel constrained to only work on these issues. We simply maintain the list to make it easier for the community to find issues that don't assume a lot of prior knowledge with the project codebase.
If you're working on a code patch or other task, you'll want to get assigned to the corresponding issue. If this is your first contribution, post a comment to the issue that you're interested in and one of the committers will add you as a contributor to the project and assign the issue to you. After you've been added as a contributor, you'll be able to assign issues to yourself.
Kite's source code and documentation are hosted on Github. Pull requests are the easiest form of contribution to accept and are preferred. If this sounds like Klingon to you, Github has an excellent description of using pull requests. We follow the Fork & Pull model described in the Github documentation.
Be sure to reference the issue number (e.g. CDK-555) in the title of your pull request so that it's easy for us to track submissions to issues. After the pull request has been created, you may also post a link to the pull request as a comment on the issue.
Kite follows a review then commit model. That means that all code submissions, including submissions by committers, are reviewed by members of the community prior to being committed to the project. After you pull request is submitted, others in the community will review your work and provide feedback. Everyone is welcome to participate in the feedback process, not just committers. In particular, we love to see contributors and newbies provide feedback to help increase broad participation by the community. Be sure to check out the tips below for some good recommendations on how to receive and respond to feedback. Remember, our feedback should always be directed at the code, not the person.
After your patch has been approved by one or more committers on the project, they will perform the last step of merging your code with the project. They may ask for you to rebase and/or squash the commits in your pull request prior to merging. Rich Jones has a [useful post] on contributing patches through GitHub, including a section on rebasing squashing commits. If you need help with the process, just send a note to the cdk-dev group and we'll get you sorted.
Contributions are strongly encouraged. It's the easiest way to get the features you want into the code, and fast. However, the project maintainers are tasked with developing software for many people with diverse requirements and, as a result, may not accept all contributions. Here are some tips for ensuring a contribution is accepted.
-
Think about everyone.
It's really important to remember that many people use this software. Features, improvements, or changes that do not apply to a wide audience may not make sense to include in the project. Put yourself in other people's shoes and ask if this is something that is useful to them.
-
Follow existing style and standards.
It's critical that the code base, docs, and examples behave and look the same. If some parts of the code use different libraries to do the same thing, have slightly different semantics or guarantees, use different naming conventions, or track different standards, it's very likely your contribution can't be accepted. Put yourself in the shoes of a new contributor; they should only have to learn a single way of doing things.
-
Accept feedback and provide rationale.
It's likely that you'll receive feedback on your contribution, especially those who are new to contributing to open source projects. Don't panic! We're all very nice people. Keep a few things in mind:
- If we disagree, help us understand the rationale behind a decision. Maybe we're missing something.
- Questions are usually just questions, and are not meant to question your ability. It's just as awkward for us to ask as it is for you to "defend" your decisions. Bear with us, and remember that our goal is to serve the larger community of users.
- It helps to detach your idea from your implementation. Sometimes, you may be asked to make changes to your implementation, but everyone agrees that the idea is great. Be open to that.
- Many times feedback is subjective. Words like "elegant," "simple," and "easy" are often thrown around, but hard to define. It's important to recognize that one person's "simple" is another person's "complex," except in the case of "simply complex."
- We are incredibly grateful you took the time to contribute, even if we decide we can't accept your code.
-
Disagree and commit
Sometimes, there's no compromise, no middle ground. Sometimes, people are just going to see things differently. Some people like baseball; not everything in life makes sense. When this happens, please understand we're all just trying to do what we think is right. If a contribution is rejected, or something doesn't make sense, tell us, accept the decision, and move on.
Watch this (it's only 2 min 38 sec): Agree and Commit, Disagree and Commit
Now watch it again: Agree and Commit, Disagree and Commit