Apache Calcite Calcite Logo

Developing Calcite

Want to help add a feature or fix a bug?

Source code

You can get the source code by downloading a release or from source control.

Calcite uses git for version control. The canonical source is in Apache, but most people find the Github mirror more user-friendly.

Download source, build, and run tests

Prerequisites are git, maven (3.5.2 or later) and Java (JDK 8 or later, 9 preferred) on your path.

Create a local copy of the git repository, cd to its root directory, then build using maven:

$ git clone git://github.com/apache/calcite.git
$ cd calcite
$ mvn install

The HOWTO describes how to build from a source distribution, set up an IDE for contributing, run more or fewer tests and run integration tests.

Contributing

We welcome contributions.

If you are planning to make a large contribution, talk to us first! It helps to agree on the general approach. Log a JIRA case for your proposed feature or start a discussion on the dev list.

Fork the GitHub repository, and create a branch for your feature.

Develop your feature and test cases, and make sure that mvn install succeeds. (Run extra tests if your change warrants it.)

Commit your change to your branch, and use a comment that starts with the JIRA case number, like this:

[CALCITE-345] AssertionError in RexToLixTranslator comparing to date literal

If your change had multiple commits, use git rebase -i master to squash them into a single commit, and to bring your code up to date with the latest on the main line.

In order to keep the commit history clean and uniform, you should respect the following guidelines.

  • Read the messages of previous commits, and follow their style.
  • The first line of the commit message must be a concise and useful description of the change.
  • The message is often, but not always, the same as the JIRA subject. If the JIRA subject is not clear, change it (perhaps move the original subject to the description of the JIRA case, if it clarifies).
  • Start with a capital letter.
  • Do not finish with a period.
  • Use imperative mood (“Add a handler …”) rather than past tense (“Added a handler …”) or present tense (“Adds a handler …”).
  • If possible, describe the user-visible behavior that you changed (“FooCommand now creates directory if it does not exist”), rather than the implementation (“Add handler for FileNotFound”).
  • If you are fixing a bug, it is sufficient to describe the bug (“NullPointerException if user is unknown”) and people will correctly surmise that the purpose of your change is to fix the bug.
  • If you are not a committer, add your name in parentheses at the end of the message.

Then push your commit(s) to GitHub, and create a pull request from your branch to the calcite master branch. Update the JIRA case to reference your pull request, and a committer will review your changes.

The pull request may need to be updated (after its submission) for three main reasons:

  1. you identified a problem after the submission of the pull request;
  2. the reviewer requested further changes;
  3. the Travis CI build failed and the failure is not caused by your changes.

In order to update the pull request, you need to commit the changes in your branch and then push the commit(s) to GitHub. You are encouraged to use regular (non-rebased) commits on top of previously existing ones.

When pushing the changes to GitHub, you should refrain from using the --force parameter and its alternatives. You may choose to force push your changes under certain conditions:

  • the pull request has been submitted less than 10 minutes ago and there is no pending discussion (in the PR and/or in JIRA) concerning it;
  • a reviewer has explicitly asked you to perform some modifications that require the use of the --force option.

In the special case, that the Travis CI build failed and the failure is not caused by your changes create an empty commit (git commit --allow-empty) and push it.

Continuous Integration Testing

Calcite has a collection of Jenkins jobs on ASF-hosted infrastructure. They are all organized in a single view and available at https://builds.apache.org/view/A-D/view/Calcite/.

Getting started

Calcite is a community, so the first step to joining the project is to introduce yourself. Join the developers list and send an email.

If you have the chance to attend a meetup, or meet members of the community at a conference, that’s also great.

Choose an initial task to work on. It should be something really simple, such as a bug fix or a Jira task that we have labeled “newbie”. Follow the contributing guidelines to get your change committed.

After you have made several useful contributions we may invite you to become a committer. We value all contributions that help to build a vibrant community, not just code. You can contribute by testing the code, helping verify a release, writing documentation or the web site, or just by answering questions on the list.