How to contribute to Apache NiFi

We are always excited to have contributions from the community - especially from new contributors!
We are interested in accepting contributions of code, as well as documentation and even artwork that can be applied as icons or styling to the application.

Technologies

The back end of Apache NiFi is written in Java. The web tier makes use of JAX-RS, and JavaScript is extensively used to provide a user interface. We depend on several third-party JavaScript libraries, including D3 and JQuery among others. We make use of Apache Maven for our builds and Git for our version control system.

Documentation is created in AsciiDoc.

Where to Start?

Finding Issues and Extending the Project

NiFi's JIRA page can be used to find tickets that are tagged as "beginner", or you can dig into any of the tickets for creating Processors. Processors should be self-contained and not rely on other outside components (except for Controller Services), so they make for excellent starting points for new NiFi developers to get started. This exposes the developer to the NiFi API and is the most extensible part of the dataflow system. The NiFi Developer Guide provides details on how to get started with the NiFi API as well as best practices and common approaches to component design.

Documentation Contributions

System-level and overview documentation is located in '<code checkout location>/nifi/nifi-docs/src/main/asciidoc'.
Tools available to facilitate documentation generation are available at Editing AsciiDoc with Live Preview.

Create a ticket for new bugs or features

Run into a bug or think there is something that would benefit the project?  Regardless if you have the time to provide the fix or implementation, we encourage any such items to be filed as an issue at the Apache NiFi JIRA.

Providing code or documentation contributions

The source is hosted at http://git-wip-us.apache.org/repos/asf/incubator-nifi.git

Like all Apache projects, a mirror of the git repository is also located on GitHub at https://github.com/apache/incubator-nifi which provides ease in forking and generating pull requests (PRs).

Clone a copy of the repository

From the Apache Hosted Repository

git clone http://git-wip-us.apache.org/repos/asf/incubator-nifi.git

From the GitHub Mirror

git clone https://github.com/apache/incubator-nifi.git


From your GitHub Fork

git clone git@github.com:<account name>/incubator-nifi.git

Retrieval of upstream changes

Additionally, it is beneficial to add a git remote for the mirror to allow the retrieval of upstream changes

git remote add upstream https://github.com/apache/incubator-nifi.git

Checkout the 'develop' branch

git checkout -b develop origin/develop will create a local, tracking branch named develop.

Why am I using 'develop' instead of 'master'? A brief summary of the Gitflow development model.

Apache NiFi (incubating) conducts development under the Gitflow model. Key points of emphasis include:

• Use of a central repository
• Branch per feature similar to the Feature Branch Workflow
• Work is done locally and then pushed to the central repo
• Two core branches are used to record the history of the project
  • 'master' - contains the official release history
  • 'develop' - parent branch from which feature branches are based and the target branch for completed features to be merged

For a more in-depth guide, visit Gitflow Workflow by Atlassian as well as the original presentation of the development model by Vincent Driessen.

Perform your code changes

Create a feature branch

Typically, there is a 1-to-1 mapping of a branch to a backing ticket as specified in JIRA.

Create a local branch that relates the associated JIRA issue with the branch.  Such an example would be:

git checkout -b nifi-359 develop

This provides instant traceability to the supporting issue and provides a means of linking discussion.

Test your changes

For code changes, ensure that the full suite of tests is executed via mvn -Pcontrib-check clean install at the root nifi folder.  Please write or update unit tests to verify your changes.

Did your change introduce new dependencies?  Are these dependencies licensed in a way that is compatible for inclusion under ASF 2.0?  Did you update the LICENSE file?

For documentation related changes, ensure that format looks appropriate for the output in which it is rendered.

Commit your changes

List the current files that have changes

$ git status
On branch nifi-359
Changes not staged for commit:
 (use "git add <file>..." to update what will be committed)
 (use "git checkout -- <file>..." to discard changes in working directory)

modified: nifi/nifi-docs/src/main/asciidoc/contributor-guide.adoc

no changes added to commit (use "git add" and/or "git commit -a")

Stage the file(s) to be committed with git add

$ git add nifi/nifi-docs/src/main/asciidoc/contributor-guide.adoc

$ git status
On branch nifi-359
Changes to be committed:
 (use "git reset HEAD <file>..." to unstage)

modified: nifi-docs/src/main/asciidoc/contributor-guide.adoc

In the case of multiple files, it is also possible to stage all tracked files through git add .

Perform the commit

In the interest of providing traceability, it is helpful to lead off your commit with the associated JIRA issue number and a summary of the change this commit is providing. Such an example is:

$ git commit -m "nifi-359 Adding a guide for procedure and best practices in contributing to the project."

The issue being listed first provides easy access to the supporting ticket and ensures it is not truncated from the varied means in which commits will be viewed.

Supplying a contribution

There are currently two paths from which we review and accept contributions, ASF JIRA and GitHub Pull Requests (PRs), regardless of whether your contribution is source code or documentation.

Supplying a contribution through patch and JIRA issue

`git format-patch`

TODO: Provide remaining steps of attaching to ticket, setting status, and the eventual auto-build verification

Supplying a contribution through a pull request (PR) via GitHub

Push changes to your personal, GitHub repository remote

Typically, this remote is listed as origin. To confirm, perform a git remote -v from within your cloned repository directory.

$ git remote -v
origin git@github.com:apiri/incubator-nifi.git (push)
origin git@github.com:apiri/incubator-nifi.git (fetch)
upstream https://git-wip-us.apache.org/repos/asf/incubator-nifi.git (fetch)

Once the appropriate remote (remote name) is determined, it is possible to push the branch with your changes to GitHub through:

$ git push <remote name> <branch name>

As an example, based on the context of this guide, this would take the form of:

$ git push origin nifi-359

This will update your fork of NiFi and can be verified from your GitHub personal project page:

Opening a Pull Request (PR) to the NiFi project

From your personal fork, a Pull Request can be opened simply by selecting the Pull Request link highlighted below.

This will allow specification of the your branch which has the changes, and will open a PR for review by the committers of the project.

Additional notes on code contributions

Code Style

This is a developing standard and will be updated to reflect an agreed upon format further supported by the maven-checkstyle-plugin.

TODO: Provide code formatters for the common IDEs

Contact us!