Getting Started
Documentation

Contributor's Corner

Apache Samza is developed by an open and friendly community. Everybody is welcome to contribute and engage with the community. There are many such opportunities:

  • ask or answer questions
  • review proposed design ideas
  • improve the documentation
  • contribute bug reports
  • write new sample applications
  • add new or improve existing test cases
  • add new libraries (new IO systems, etc)
  • work on the core Samza stream processing framework
  • review design proposals and documents

Ask Questions

Apache Samza community is happy to answer any questions related to the project with any communication channels listed in mailing list.

File Bug Reports

Apache Samza uses JIRA to file bug reports. In order to file a bug report, please open Samza JIRA and include the following details:

  • A descriptive title
  • Description of the issue you are facing
  • Version of Apache Samza in which this issue is seen - You can add the version(s) by updating “Affects Version/s” field in the JIRA
  • Environment details (such as OS, JDK version etc) whenever applicable

If you need someone to immediately take a look at your JIRA, please don’t hesitate to send an email to the dev mailing list.

Find A Project to Work On

We tag tickets in JIRA with “newbie” label that are good for people getting started with the code base. When you feel confident, you can pick-up “newbie++” JIRAs. Picking up these JIRAs are the best way to familiarize yourself with the codebase.

More meaty projects are here. The process for working on a large project is documented in details in samza enhancement proposal. If you are unclear whether a change you are proposing requires a design document, ask us through our mailing list.

Contributing Documentation

The Samza documentation is based on markdown files, which are built using Jekyll. To propose a change to documentation, edit their corresponding markdown source files in Samza’s docs/ directory. The README.md in the same directory shows how to build the documentation locally and test your changes. The process to propose a doc change is otherwise the same as the process for proposing code changes below.

Contributing to Apache Samza

The official Samza codebase is hosted on the Apache Git repository located here and we use Pull Requests on GitHub for code reviews. If you are unfamiliar with this workflow, Git Handbook has many useful introductions and instructions.

You should fork the Samza’s Github repository to create your own repository.

Building and Testing

We use Gradle to build and test Samza. You do not need to install gradle, but you do need a Java SDK installed. You can develop on Linux and macOS.

The entire set of unit tests can be run with this command at the root of the git repository.

./gradlew test

Developing with an IDE

Generate an IDEA project .ipr file with:

./gradlew idea

Pull Requests

If there is no JIRA ticket for your work, please open one before creating a Pull Request. If it is a trivial fix (such as a typo, doc fix etc), you may skip ticket creation. Here’s the development workflow:

  • Create a new branch in your repository and push your changes to that branch
  • Open a Pull Request against the “master” branch of apache/samza
    • Make sure that the Pull Request title is of the format “SAMZA-<JiraNumber> : <JiraTitle>”
    • Make sure that your patch cleanly applies against the master branch. If not, rebase before creating the Pull Request
    • Optional: add a reviewer by @ the username
  • Ping us if we don’t follow up on your JIRA in a timely fashion.
  • If your Pull Request is approved, it will automatically be closed, along with any associated JIRA ticket when a committer merges your changes.
  • If your Pull Request is not approved and requires changes based on reviews, please make changes and update the Pull Request.
    • Fixes can simply be pushed to the same branch from which you opened your pull request.
    • Please address feedback via additional commits instead of amending existing commits. This makes it easier for the reviewers to know what has changed since the last review.
    • Jenkins will automatically re-test when new commits are pushed.
    • Despite our efforts, Samza may have flaky tests at any given point, if the failure is unrelated to your pull request and you have been able to run the tests locally successfully, please mention it in the pull request.
  • If your Pull Request is rejected or discarded for whatever reason, please close it promptly because committers cannot close your Pull Requests since committers cannot close them.