Interested in contributing patches to Samza? This page will get you started.
Rules
Style
Please read this page for coding style suggestions.
Tests
Setup
Install rbt to make life easier.
sudo easy_install -U RBTools
Contributor Workflow
After setting up, you'll want to checkout the code.
...
Table of Contents
Apache Samza is developed by an open and friendly community. Everybody is welcome to contribute and engage with the community. We are happy to accept contributions, be it trivial cleanups or bug-fix or new features. There are many ways to engage with the community and contribute to Apache Samza, including filing bugs, asking questions and joining discussions in our mailing lists, contributing code or documentation, or testing.
Ask Questions
Apache Samza community is happy to answer any questions related to the project. We use our mailing list for all communications and discussions. You can also interact in StackOverflow under the tag - #apache-samza
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 bugs 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:
- Instigate a discussion on the JIRA
- Write a design document
- Request feedback for the design document on the Jira and the samza-dev mailing list
- Come to an agreement on design
- Implement design
If you are unclear whether a change you are proposing requires a design document, feel free ask us through our mailing list!
Contributor Workflow
Setup
Samza’s code is in an Apache Git repository located here.
You can check out Samza’s code by running:
Code Block | ||
---|---|---|
| ||
git clone http://git-wip-us.apache.org/repos/asf/samza.git |
...
To work on a JIRA once you've checked out, create a new branch.
git branch SAMZA-2
Now you can checkout the branch to work on it.
git checkout SAMZA-2
Once you've committed some changes to the branch, you can submit your patch to Review Board.
rbt post --summary "SAMZA-2: fix the bug of .." --description "Detailed description of my patch"
The post command will spit out a URL. Verify that everything looks good, and then publish the review.
rbt publish 13725
Publishing will notify the dev mailing list that a new review request has been published.
The JIRA for the bug you're working on should be updated as well. Start by downloading the diff from Review Board.
curl https://reviews.apache.org/r/13725/diff/raw/ > /tmp/SAMZA-2.0.patch
Next, visit the JIRA page (e.g. https://issues.apache.org/jira/browse/SAMZA-2), and attach the patch file with a comment that points to the review board. See this example.
After you got some reviews and updated your working branch accordingly, you can update the review board:
rbt post -r 13725 --description "Description of my updated code"
Committer Workflow
If you have commit access on the apache repository then you will not be applying patches in the manner described in the contributor workflow. Instead, once your patch has been reviewed you will check it in yourself as follows:
Create a branch to work on:
git fetch
git checkout -b xyz origin/master
- Implement the feature.
Rebase:
git rebase origin/master
- Post the change to JIRA and get it reviewed.
- Push the change back to Apache. Pick one of the following:
Style
Please read this page for coding style suggestions.
Tests
Please read this page for running various tests in Samza.
Website
The Samza website is built by Jekyll from the markdown files found in the docs
subdirectory.
Contribute using Pull Requests
We use Pull Requests to review and discuss your contributions. In order to contribute code, please do the following:
- If you are working on a big new feature, follow the steps outlined above regarding design documents page
- If there is no JIRA for your work, please open a JIRA before creating a Pull Request. If it is a trivial fix (such as typo, doc fix etc), you may skip the JIRA creation.
- Creating Pull Request
- Fork the Github repository at http://github.com/apache/samza if you haven’t already
- Create a new branch in your repository and push your changes to that branch
- Make sure you have observed the recommendations in the coding guide and testing
- 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
- Change the status of the JIRA to “Patch Available” so that it notifies the committers of the patch being available
- Nag 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, with any associated JIRA when a committer merges your changes.
- If your Pull Request is not approved and requires changes based on reviews, please make changes to your patch.
- While making the changes, kindly update the JIRA status from “Patch Available” to “In Progress”.
- Make sure that you have rebased your branch to latest in the master branch before updating the Pull Request. This will help avoid conflicts during the merge. We cannot commit patches that have merge conflicts!
- If your Pull Request is rejected for whatever reason, please close it promptly because committers cannot close your Pull Requests!
Committer Workflow
Enabling merging through GitHub
- Prerequisites
- Apache ID (should have been set up in the initial committer onboarding process)
- You should be added as a committer to the Samza project (should have been set up in the initial committer onboarding process)
- Github account
- Join Apache Github organization
- Open https://id.apache.org/ and log into your Apache account.
- Fill in your GitHub username and save your change:
- An organization invitation email will be sent (usually in 30min, may up to few hours)
- Accept the invitation.
- An email confirming to add you as Samza committer will be sent (usually in 30min, may up to few hours) .
- Enable 2FA on Github
- This page (https://help.github.com/en/articles/configuring-two-factor-authentication) might be helpful for that.
- Link Apache and Github account
- Authorize Apache by clicking "Start ASF Oauth"
- Authorize GitHub Account
- Once your writer access is granted, you will see
- Congratulations! Now you have write access to Apache Samza Project!
Merging a pull request (PR)
- Make sure the PR can be cleanly merged (GitHub should report if it can be cleanly merged).
- At the bottom of the feed for the PR, there is a button with a selection dropdown for merging a branch. Make sure the "Squash and merge" option is selected, and then click "Squash and merge".
- Whenever possible, make sure that the commit title includes the JIRA number and title.
Other notes
- The committer workflow used to involve running a "merge-pull-request.py" script. That flow is no longer applicable.
- For committers wishing to update the webpage, please see docs/README.md for instructions.
# assuming master is up-to-date with origin
git checkout master
git merge --squash xyz
git commit -am
"SAMZA-XXX xyz feature"
--author=
"firstname lastname <contributoremail>"
...