Contributing Guidelines

Thank you for your interest in Alluxio! We greatly appreciate any new features or fixes.

New Contributors

If you are a new contributor to the Alluxio open source project, please visit the Contributing Getting Started Guide for a tutorial on how to contribute to Alluxio.

Alluxio Getting Started Tasks

There are a few things that new contributors can do to familiarize themselves with Alluxio:

  1. Run Alluxio Locally
  2. Run Alluxio on a Cluster
  3. Read Configuration-Settings and Command-Line Interface
  4. Read a Code Example
  5. Build Alluxio Master Branch
  6. Fork the repository, add unit tests or javadoc for one or two files, and submit a pull request. You are also welcome to address issues in our JIRA. Here is a list of unassigned New Contributor Tasks. Please limit 2 tasks per New Contributor. Afterwards, try some Beginner/Intermediate tasks, or ask in the User Mailing List. For a tutorial, see the GitHub guides on forking a repo and sending a pull request.

Submitting Code

  • We encourage you to break your work into small, single-purpose patches if possible. It is much harder to merge in a large change with a lot of disjoint features.
  • We track issues and features in our JIRA. If you have not registered an account, please do so!
  • Open a ticket in JIRA detailing the proposed change and what purpose it serves.
  • Submit the patch as a GitHub pull request. For a tutorial, see the GitHub guides on forking a repo and sending a pull request.
  • In your pull request title, make sure to reference the JIRA ticket. This will connect the ticket to the proposed code changes. for example:
[ALLUXIO-100] Implement an awesome new feature
  • In the description field of the pull request, please include a link to the JIRA ticket.

Note that for some minor changes it is not required to create corresponding JIRA tickets before submiting the pull requests. For instance:

  • For pull requests that only address typos or formatting issues in source code, you can prefix the titles of your pull requests with “[SMALLFIX]”, for example:
[SMALLFIX] Fix formatting in Foo.java
  • For pull requests that improve the documentation of Alluxio project website (e.g., modify the markdown files in docs directory), you can prefix the titles of your pull requests with “[DOCFIX]”. For example, to edit this web page which is generated from docs/Contributing-to-Alluxio.md, the title can be:
[DOCFIX] Improve documentation of how to contribute to Alluxio

Testing

  • Some tests require libfuse installed. Make sure you have installed the correct libraries mentioned in this page.

  • Run all unit tests with mvn test (will use the local filesystem as the under filesystem and HDFS 1.0.4 as the under filesystem in the HDFS module). mvn -Dhadoop.version=2.4.0 test will use HDFS 2.4.0 as the under filesystem for the HDFS module tests.

  • To run tests against specific under filesystems, execute the maven command from the desired submodule directory. For example, to run tests for HDFS you would run mvn test from alluxio/underfs/hdfs.

  • Run a single unit test: mvn -Dtest=AlluxioFSTest#createFileTest -DfailIfNoTests=false test

  • To quickly test the working of some APIs in an interactive manner, you may leverage the Scala shell, as discussed in this blog.

  • Run tests with a different Hadoop version: mvn -Dhadoop.version=2.2.0 clean test

  • Run tests with Hadoop FileSystem contract tests (uses hadoop 2.6.0): mvn -PcontractTest clean test

Coding Style

  • Please follow the style of the existing codebase. Specifically, we use Google Java style, with the following changes or deviations:
    • Maximum line length of 100 characters.
    • Third-party imports are grouped together to make IDE formatting much simpler.
    • Class member variable names should be prefixed with m, for example private WorkerClient mWorkerClient;
    • Static variable names should be prefixed with s, for example public static String sUnderFSAddress;
  • Bash scripts follow Google Shell style, and must be compatible with Bash 3.x
  • You can download our Eclipse formatter
    • For Eclipse to organize your imports correctly, configure “Organize Imports” to look like this
    • If you use IntelliJ IDEA:
      • You can either use our formatter with the help from Eclipse Code Formatter or use Eclipse Code Formatter Plugin in IntelliJ IDEA.
      • To automatically format the import, configure in Preferences->Code Style->Java->Imports->Import Layout according to this order
      • To automatically reorder methods alphabetically, try the Rearranger Plugin, open Preferences, search for rearranger, remove the unnecessary comments, then right click, choose “Rearrange”, codes will be formatted to what you want
  • Alluxio is using SLF4J for logging with typical usage pattern of:
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public MyClass {

  private static final Logger LOG = LoggerFactory.getLogger(MyClass.class);

    public void someMethod() {
      LOG.info("Hello world");
    }
}
  • To verify that the coding standards match, you should run checkstyle before sending a pull-request to verify no new warnings are introduced:
$ mvn checkstyle:checkstyle

FindBugs

Before submitting the pull-request, run the latest code against FindBugs to verify no new warnings are introduced.

$ mvn compile findbugs:findbugs

IDE

You can generate an Eclipse configuration file by running:

$ mvn clean -Pdeveloper install -DskipTests
$ mvn clean -Pdeveloper -DskipTests eclipse:eclipse -DdownloadJavadocs=true -DdownloadSources=true

Then import the folder into Eclipse.

You may also have to add the classpath variable M2_REPO by running:

$ mvn -Declipse.workspace="your Eclipse Workspace" eclipse:configure-workspace

If you are using IntelliJ IDEA, you may need to change the Maven profile to ‘developer’ in order to avoid import errors. You can do this by going to

View > Tool Windows > Maven Projects
Need help? Ask a Question