The Kiji project is open source–we welcome your active participation in the user and developer communities, and your contributions to the project source code.
Read the sections below to learn about the Kiji development process, how to get involved, and how to help contribute.
Kiji users should sign up for the Kiji user list for information about the Kiji project as well as user-to-user support:
Kiji community members interested in observing or participating in the development of Kiji itself should sign up for the Kiji developer list:
Also of interest to developers: updates from the issue database are emailed to email@example.com.
Source code for all Kiji components is available at github.com/kijiproject.
To download Kiji source code you will need to install git on your computer. Learn more about git.
All Kiji source code is made available under the terms of the Apache 2.0 License.
All bug reports, new features, and improvements are tracked through our JIRA instance at jira.kiji.org. If you want to report an issue with Kiji, please file a bug report here.
Documentation related to the development of Kiji (style guides, workflows, processes and standards, etc) is tracked in a wiki at https://github.com/kijiproject/wiki/wiki.
Contributing to Kiji
This section describes the workflow for contributing to Kiji. Please read on if you are interested in helping us improve Kiji.
Download Development Tools
You will need the following tools to build and modify Kiji:
Download Source Code
First, download the source code from github.com/kijiproject. Each repository contains a different component of the complete framework. You can modify any individual component without needing to download all the components, though you may be asked to test your changes with downstream components to verify compatibility.
If you are not already a github user, you should sign up for github. (It’s free!) Then click the “fork” button in the project to create a private fork.
Individual components can also be directly cloned with the following command:
$ git clone https://github.com/kijiproject/project-name.git
Find an Issue to Work On
We track all development using JIRA at jira.kiji.org.
For a place to start, browse open issues in KijiSchema
If you have an idea for a new feature, you should create a JIRA ticket for the feature under the appropriate project. It’s best to discuss ideas on the mailing list first so everyone understands how your changes work. You can also use the “comments” feature on the JIRA instance to hold a discussion about an issue.
Make a topic branch in your git repository, make your changes, and commit them with
git commit. Please respect the following workflow for contributions:
- Include test cases to confirm bug fixes or validate correct behavior of new features.
mvn verifyto test your changes. If your changes may impact other projects, use
mvn installand then run
mvn verifyin the affected projects.
- A contribution should be held in a single commit. Use
git rebase -ito squash multiple intermediate commits into a final commit.
- Code should build without introducing any test failures, findbugs errors, or checkstyle warnings. Scala projects should have no new scalastyle errors. You should explicitly suppress Java compiler warnings created by your code if you believe them to be unavoidable.
- When you are ready, upload a patch on our reviewboard instance (review.kiji.org). You should put one or more usernames in the “people” field when creating the review, so that we get notified; please select usernames from the REVIEWERS file in the root of the git project you’re hacking on.
- Note: the post-review tool may be helpful to upload patches for review. To create a patch to upload manually, you should run
git diff --full-index master..HEAD > filename.patch.
- Please comment on the associated JIRA issue to link to the associated review.
- Wrap lines at 100 characters.
- Indent by 2 spaces. Do not use tab characters.
- Do not leave trailing whitespace on lines.
- New files must have the Apache 2.0 License header at the top.
- Do not use @author tags or “sign” your // TODO comments. If you want to mark a TODO item in code that requires more than a sentence to describe, or believe it is a critical issue, you should create a JIRA ticket for the problem (possibly as a subtask of your original ticket), and reference it in code like:
// TODO(SCHEMA-1234): Use the FooBar subsystem when it's available.
- Include Javadoc with all classes, methods, and fields.
- Update documentation in the documentation project as applicable, and submit this along with your primary change.
- Several more subtle rules are listed in the Kiji code style guide
Please make changes to work with one of the committers to create a patch that can be accepted into the master branch. Multiple cycles of review may be required to prepare a large change for acceptance into the project source.
A list of individuals (really their JIRA/reviewboard usernames) who perform code reviews is given in a file at the top level of each git repository named /REVIEWERS.
After a committer has accepted your patch and pushed it to the master branch, the corresponding issue in JIRA will be marked as “Resolved.” This will be part of a future Kiji release. Thank you for helping us make Kiji great!
We will incorporate your change using the “merge locally” technique described in this github help article. We rebase new changes off the master branch to keep a linear history.
The documentation project is called kijiproject.github.com. We use markdown for documentation. You can learn more about markdown syntax here. Our docs will be transformed into readable pages using Jekyll. To add to the docs:
- Fork the documentation project.
- Refer to README.md in the parent directory for further instructions.
- Refer to markdown_styleguide.md in the parent directory for more on the syntax.
- Create a topic branch:
git checkout -b my_fix.
- Make your changes.
- Push your branch:
git push origin my_fix.
- Use pull requests to contribute your changes once you are done.