Page History

...

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.  

...

Samza’s code is in an Apache Git repository located here.

You can check out Samza’s code by running:

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

After you have made somce committed changes to the branch, and before you want to submit your patch to Review Board, a few things need to be done:

  1. Run unit tests:

  ./gradlew clean build

  2. Check if your code follows the coding conventions:

  ./gradlew checkstyleMain checkstyleTest

Once you've finished the above checklist, you can submit your patch:

 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"

 rbt publish 13725

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:

1. Create a branch to work on:

    

   git fetch git checkout -b xyz origin/master

2. Implement the feature.

3. Rebase:

    

   git rebase origin/master

4. Post the change to JIRA and get it reviewed.
5. Push the change back to Apache. Pick one of the following:

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
  1. Fork the Github repository at http://github.com/apache/samza if you haven’t already
  2. 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
  3. 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
  4. 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

If you are a committer you need to use https instead of http to check in, otherwise you will get an error regarding an inability to acquire a lock. Note that older versions of git may also give this error even when the repo was cloned with https; if you experience this try a newer version of git.

Prepare to merge a Pull Request (PR) by setting up the following:

1. Setup JIRA on your host
   • Install Jira packages - sudo pip install jira
   • Set the JIRA_USERNAME and JIRA_PASSWORD environment variables with the appropriate credentials for interacting with Jira. This is required to correctly close the JIRA associated with the PR
2. Setup aliases for the remote repositories:(Samza Github repo and Apache Samza Repo)
   • Add ASF git repo for committing the PR git remote add samza-apache https://git­wip­us.apache.org/repos/asf/samza.git
   • Add Github repo for fetching the patch from the PR git remote add samza-github https://github.com/apache/samza.git
3. Set up API tokens for Git
   • Create an OAuth key for making requests to the GitHub API. If this is not defined, then requests will be unauthenticated and you can’t access the API. An OAuth key for the API can be created at https://github.com/settings/tokens
   • Set the created OAuth key as GITHUB_OAUTH_KEY environment variable.

Merging a Pull Request

• Committers can use the bin/merge-pull-request.py script to merge an approved PR. The script is interactive and will walk you through the steps for merging the patch, closing the PR and the associated JIRA. cd samza ./bin/merge-pull-request.py
• Whenever possible, make sure that the commit title includes the JIRA number and title.
• Merging changes that don’t cleanly apply on the master should be avoided.
• For committers wishing to update the webpage, please see docs/README.md for instructions.

...