How to contribute

Zeppelin is Apache2 License Software. Contributing to Zeppelin (Source code, Documents, Image, Website) means you agree to the Apache2 License.

  1. Make sure your issue is not already in the Jira issue tracker
  2. If not, create a ticket describing the change you're proposing in the Jira issue tracker
  3. Contribute your patch via Pull Request.

Creating a Pull Request

In order to make the review process easier, please follow this template when making a Pull Request:

### What is this PR for?
A few sentences describing the overall goals of the pull request's commits.

### What type of PR is it?
[Bug Fix | Improvement | Feature | Documentation | Hot Fix | Refactoring]

### Todos
* [ ] - Task

### Is there a relevant Jira issue?

### How should this be tested?
Outline the steps to test the PR here.

### Screenshots (if appropriate)

### Questions:
* Does the licenses files need update?
* Is there breaking changes for older versions?
* Does this needs documentation?

You can also use this small bookmarklet tool to fill your Pull Request fields automatically:

javascript:(function() {var e = document.getElementById('pull_request_body');if (e) {e.value += '### What is this PR for?\nA few sentences describing the overall goals of the pull request\'s commits.\n\n### What type of PR is it?\n[Bug Fix | Improvement | Feature | Documentation | Hot Fix | Refactoring]\n\n### Todos\n* [ ] - Task\n\n### Is there a relevant Jira issue?\n\n### How should this be tested?\nOutline the steps to test the PR here.\n\n### Screenshots (if appropriate)\n\n### Questions:\n* Does the licenses files need update?\n* Is there breaking changes for older versions?\n* Does this needs documentation?';}})();

Source Control Workflow

Zeppelin follows [Fork & Pull] (https://github.com/sevntu-checkstyle/sevntu.checkstyle/wiki/Development-workflow-with-Git:-Fork,-Branching,-Commits,-and-Pull-Request) model.

The Review Process

When a Pull Request is submitted, it is being merged or rejected by following review process.

  • Anybody can be a reviewer and may comment on the change and suggest modifications.
  • Reviewer can indicate that a patch looks suitable for merging with a comment such as: “Looks good”, “LGTM”, “+1”.
  • At least one indication of suitable for merging (e.g. “LGTM”) from committer is required to be merged.
  • Pull request is open for 1 or 2 days for potential additional review, unless it's got enough indication of suitable for merging.
  • Committer can initiate lazy consensus (“Merge if there is no more discussion”) and the code can be merged after certain time (normally 24 hours) when there is no review exists.
  • Contributor can ping reviewers (including committer) by commenting ‘Ready to review’ or suitable indication.

Becoming a Committer

The PPMC adds new committers from the active contributors, based on their contribution to Zeppelin. The qualifications for new committers include:

  1. Sustained contributions: Committers should have a history of constant contributions to Zeppelin.
  2. Quality of contributions: Committers more than any other community member should submit simple, well-tested, and well-designed patches.
  3. Community involvement: Committers should have a constructive and friendly attitude in all community interactions. They should also be active on the dev, user list and reviewing patches. Also help new contributors and users.

Setting up

Here are some things you will need to build and test Zeppelin.

Software Configuration Management (SCM)

Zeppelin uses Git for its SCM system. http://git.apache.org/incubator-zeppelin.git you'll need git client installed in your development machine. For write access, https://git-wip-us.apache.org/repos/asf/incubator-zeppelin.git

Integrated Development Environment (IDE)

You are free to use whatever IDE you prefer, or your favorite command line editor.

Project Structure

Zeppelin project is based on Maven. Maven works by convention & defines [directory structure] (https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html) for a project. The top-level pom.xml describes the basic project structure. Currently Zeppelin has the following modules.

<module>zeppelin-interpreter</module>
<module>zeppelin-zengine</module>
<module>spark</module>
<module>markdown</module>
<module>angular</module>
<module>shell</module>
<module>hive</module>
<module>tajo</module>
<module>flink</module>
<module>ignite</module>
<module>lens</module>
<module>cassandra</module>
<module>zeppelin-web</module>
<module>zeppelin-server</module>
<module>zeppelin-distribution</module>

Web Project Contribution Guidelines

If you plan on making a contribution to Zeppelin's WebApplication, please check its own contribution guidelines

Code convention

We are following Google Code style:

Check style report location are in ${submodule}/target/site/checkstyle.html Test coverage report location are in ${submodule}/target/site/cobertura/index.html

Build Tools

To build the code, install

  • Oracle Java 7
  • Apache Maven

Getting the source code

First of all, you need the Zeppelin source code. The official location for Zeppelin is http://git.apache.org/incubator-zeppelin.git.

git access

Get the source code on your development machine using git.

git clone http://git.apache.org/incubator-zeppelin.git zeppelin

You may also want to develop against a specific release. For example, for branch-0.1

git clone -b branch-0.1 http://git.apache.org/incubator-zeppelin.git zeppelin

or with write access

git clone https://git-wip-us.apache.org/repos/asf/incubator-zeppelin.git

Fork repository

If you want not only build Zeppelin but also make change, then you need fork Zeppelin github mirror repository (https://github.com/apache/incubator-zeppelin) and make pull request.

Build

mvn install

To skip test

mvn install -DskipTests

To build with specific spark / hadoop version

mvn install -Phadoop-2.2 -Dhadoop.version=2.2.0 -Pspark-1.3 -Dspark.version=1.3.0

Tests

Each new File should have its own accompanying unit tests. Each new interpreter should have come with its tests.

Zeppelin has 3 types of tests:

  1. Unit Tests: The unit tests run as part of each package‘s build. E.g. SparkInterpeter Module’s unit test is SparkInterpreterTest
  2. Integration Tests: The integration tests run after all modules are build. The integration tests launch an instance of Zeppelin server. ZeppelinRestApiTest is an example integration test.
  3. GUI integration tests: These tests validate the Zeppelin UI elements. These tests require a running Zeppelin server and launches a web browser to validate Notebook UI elements like Notes and their execution. See ZeppelinIT as an example.

Currently the GUI integration tests are not run in the Maven and are only run in the CI environment when the pull request is submitted to github. Make sure to watch the [CI results] (https://travis-ci.org/apache/incubator-zeppelin/pull_requests) for your pull request.

Continuous Integration

Zeppelin uses Travis for CI. In the project root there is .travis.yml that configures CI and [publishes CI results] (https://travis-ci.org/apache/incubator-zeppelin/builds)

Run Zeppelin server in development mode

cd zeppelin-server
HADOOP_HOME=YOUR_HADOOP_HOME JAVA_HOME=YOUR_JAVA_HOME mvn exec:java -Dexec.mainClass="com.nflabs.zeppelin.server.ZeppelinServer" -Dexec.args=""

or use daemon script

bin/zeppelin-daemon start

Server will be run on http://localhost:8080

JIRA

Zeppelin manages it's issues in Jira. https://issues.apache.org/jira/browse/ZEPPELIN

Stay involved

Everyone is welcome to join our mailing list: