Page History

Table of Contents

This page is meant to document the various steps to working with git to contribute or review Kafka code. There are probably a lot of bugs in these steps or possible better recipes, so help make this page better. If you want to push your commits without passwd, please see apache git wiki.

Overview

The Kafka project development ecosystem involves git (for version control), JIRA (for issue tracking) and Review Board (for reviewing code changes made by contributors). To make it easier for both the contributors and the reviewers to manage the contributions, the Kafka project also ships a (python based) script which automates the steps that are involved in the context of a patch submission. These steps involve:

Creating a patch/diff between the local git repo against the project remote repo
Creating a review task in Review Board and publish the patch/diff that was generated for the changes
Updating the JIRA, related to these changes, with a comment about a patch being made available and ready for review at Review Board

As you'll notice this requires (automated) integration between JIRA and Review Board. The (python based) script, which is named kafka-patch-review.py (and present in the checked out code of Kafka project), acts as a wrapper around the scripts/tools that are shipped by JIRA and Review Board for such integrations. Since the kafka-patch-review.py is merely a wrapper around those tools, you'll have to install those tools locally to be able to use the kafka-patch-review.py script. This document helps you in setting up those tools as well as helping you understand the usage of the kafka-patch-review.py itself.

Kafka patch review tool

1. Setup

...

The following sections will help you install and setup the necessary tools which this wrapper script uses for patch submission.

Install/setup jira-python package

Download the jira-python package

Code Block
sudo easy_install jira-python

Configure JIRA user name and password

The kafka-patch-review.py expects that your JIRA user name and password, that you use for https://issues.apache.org/jira JIRA instance be setup in a file named jira.ini under your home directory.

Code Block
nnarkhed-mn:~ nnarkhed$ cat ~/jira.ini user=nehanarkhede password=***********

Info
There's a JIRA to allow the patch submission script to prompt for password (optionally) instead of having it stored in this file https://issues.apache.org/jira/browse/KAFKA-1854

Install/setup review board python tools

This is a quick tutorial on using Review Board with Kafka.

Install the post-review tool

If you are on RHEL, Fedora or CentOS, follow these steps

Code Block
sudo yum install python-setuptools sudo easy_install -U RBTools

If you are on a Debian based system (like LinuxMint) follow these steps

Code Block
sudo apt-get install python-setuptools sudo easy_install -U RBTools

If you are on Mac, follow these steps

Code Block
sudo easy_install -U setuptools sudo easy_install -U RBTools

For other platforms, follow the instructions here to setup the post-review tool.

Configure review board related stuff

Then you need to configure a few things to make it work:

First set the review board url to use. You can do this from in git:

Code Block
git config reviewboard.url https://reviews.apache.org

Info

If you checked out using the git wip http url that confusingly won't work with review board. So you need to configure an override to use the non-http url. You can do this by adding a config file like this:

Code Block
jkreps$ cat ~/.reviewboardrc REPOSITORY = 'git://git.apache.org/kafka.git' TARGET_GROUPS = 'kafka' GUESS_FIELDS = True

...

Install the argparse module

Code Block
On Linux -> sudo yum install python-argparse On Mac -> sudo easy_install argparse

...

Kafka patch review tool usage

...

Code Block

nnarkhed-mn:kafka-git-idea nnarkhed$ python kafka-patch-review.py --help
usage: kafka-patch-review.py [-h] -b BRANCH -j JIRA [-s SUMMARY]
                             [-d DESCRIPTION] [-r REVIEWBOARD] [-t TESTING]
                             [-v VERSION] [-db]

Kafka patch review tool

optional arguments:
  -h, --help            show this help message and exit
  -b BRANCH, --branch BRANCH
                        Tracking branch to create diff against
  -j JIRA, --jira JIRA  JIRA corresponding to the reviewboard
  -s SUMMARY, --summary SUMMARY
                        Summary for the reviewboard
  -d DESCRIPTION, --description DESCRIPTION
                        Description for reviewboard
  -r REVIEWBOARD, --rb REVIEWBOARD
                        Review board that needs to be updated
  -t TESTING, --testing-done TESTING
                        Text for the Testing Done section of the reviewboard
  -v VERSION, --version VERSION
                        Version of the patch
  -db, --debug          Enable debug mode

...

Upload patch

Specify the branch against which the patch should be created (-b)
Specify the corresponding JIRA (-j)
Specify an optional summary (-s) and description (-d) for the reviewboard

...

Code Block
python kafka-patch-review.py -b origin/trunk -j KAFKA-42

...

Update patch

Specify the branch against which the patch should be created (-b)
Specify the corresponding JIRA (--jira)
Specify the rb to be updated (-r)
Specify an optional summary (-s) and description (-d) for the reviewboard, if you want to update it
Specify an optional version of the patch. This will be appended to the jira to create a file named JIRA-<version>.patch. The purpose is to be able to upload multiple patches to the JIRA. This has no bearing on the reviewboard update.

...

Code Block
python kafka-patch-review.py -b origin/trunk -j KAFKA-42 -r 14081

JIRA command line tool

1. Download the JIRA command line package

Install the jira-python package

Code Block
sudo easy_install jira-python

2. Configure JIRA username and password

Include a jira.ini file in your $HOME directory that contains your Apache JIRA username and password

Code Block
nnarkhed-mn:~ nnarkhed$ cat ~/jira.ini user=nehanarkhede password=***********

Reviewboard