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.

Mailing Lists

Kiji users should sign up for the Kiji user list for information about the Kiji project as well as user-to-user support:

Sign up for user@kiji.org

Kiji community members interested in observing or participating in the development of Kiji itself should sign up for the Kiji developer list:

Sign up for dev@kiji.org

Also of interest to developers: updates from the issue database are emailed to issues@kiji.org.

Sign up for issues@kiji.org

Source Code

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.

Our source code and development workflow are hosted through github, but we do not use github’s issue tracker. Read below for more information about where to report bugs or track other development issues.

All Kiji source code is made available under the terms of the Apache 2.0 License.

Issue Tracker

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.

Wiki

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.

Hack!

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.
  • Use mvn verify to test your changes. If your changes may impact other projects, use mvn install and then run mvn verify in the affected projects.
  • A contribution should be held in a single commit. Use git rebase -i to 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.

Code Style

Code should follow the Kiji code style guide. This is primarily based on the Sun Java Coding Conventions. We have the following exceptions and additional expectations for code:

  • 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

Code Review

Code is reviewed on our Reviewboard instance at review.kiji.org. Please do not submit pull requests through github. Please create a Reviewboard account with the same username as you use on JIRA.

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.

Success!

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.

Contributing Documentation

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.