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.
Simple contributor workflow
This is the simple workflow and will work well for small features development for people who don't have direct access to check in to the Apache repository. Let's assume you are working on a feature or bug called, xyz:
1. Checkout a new repository:
Code Block |
---|
git clone https://git-wip-us.apache.org/repos/asf/kafka.git kafka
|
Or if you already have a copy of the repository, just check for updates
Code Block |
---|
git fetch
|
2. Create and checkout a feature branch to work in:
Code Block |
---|
git checkout -b xyz remotes/origin/trunk
|
3. Do some work on this branch and periodically checkin locally:
Code Block |
---|
git commit -a
|
4. When done (or periodically) rebase your branch to take any changes from trunk:
Code Block |
---|
git pull --rebase origin trunk
|
5. Make a patch containing your work and upload it to JIRA:
Code Block |
---|
git format-patch trunk --stdout > xyz-v1.patch
|
6. You may need to iterate/rebase your patch a few times as people comment on the code until a commit checks it in to the main repository.
You will also want to ensure you have your username and email setup correctly so that we correctly record the source of the contribution:
Code Block |
---|
git config --global user.name "Palmer Eldritch"
git config --global user.email "peldritch@layoutsinc.com"
|
Reviewer workflow:
This assumes you already have a copy of the repository.
1. Make sure your code is up-to-date:
Code Block |
---|
git fetch
|
2. Checkout the destination branch:
Code Block |
---|
git checkout trunk
|
3. See what the patch will do:
Code Block |
---|
git apply --stat xyz-v1.patch
|
4. See that the patch will apply cleanly (otherwise prod the contributor to rebase):
Code Block |
---|
git apply --check xyz-v1.patch
|
6. Apply the patch to trunk
Code Block |
---|
git am --signoff < xyz-v1.patch
|
If you get an error that says "Patch does not have a valid e-mail address." then the patch might have been created by doing git diff in which case you can apply the patch using
Code Block |
---|
patch -p1 < xyz-v1.patch
|
if the am operation failed you will also need to remove the .git/rebase-apply/ that gets created
7. If things go wrong (tests fail, you find some problem, etc), you can back out:
Code Block |
---|
git reset --hard HEAD
git clean -f
|
8. Push the change back to Apache:
Code Block |
---|
git push origin trunk
|
Simple Commiter Workflow
If you have commit access on the apache repository then you will not be applying patches in the manner described in the reviewer workflow. Instead, once your patch has been reviewed you will check it in yourself as follows:
- Create a branch to work on:
Code Block git fetch git checkout -b xyz remotes/origin/trunk
- Implement the feature.
- Rebase:
Code Block git rebase remotes/origin/trunk
- Post the change to JIRA and get it reviewed.
- Push the change back to Apache. Pick one of the following:
- You should almost always collapse your work into a single check-in in order to avoid cluttering the upstream change-log:
Code Block # assuming trunk is up-to-date with origin git checkout trunk git merge --squash xyz git commit -am "KAFKA-XXX xyz feature; reviewed by <reviewers>" git push origin trunk
- If you are absolutely sure you want to preserve your local intermediate check-in history then push directly from your feature branch instead of the above merge (or use merge without the squash option):
Code Block # from feature branch xyz git push origin trunk
- You should almost always collapse your work into a single check-in in order to avoid cluttering the upstream change-log:
Github Workflow
Apache doesn't seem to provide a place to stash your work-in-progress branches or provide some of the nice social features github has. This can be a problem for larger features. Here are instructions for using github as a place to stash your work in progress changes.
Setting Up
1. As in the other workflows begin by checking out kafka (if you haven't already):
Code Block |
---|
git clone https://git-wip-us.apache.org/repos/asf/kafka.git kafka
|
This sets up the remote alias "origin" automatically which refers back to the Apache repo.
2. Create a new github repository on your github account to use for stashing changes. There are various ways to do this, I just forked the apache/kafka repo (https://github.com/apache/kafka) which creates a repo https://github.com/jkreps/kafka (where jkreps would be your user name).
3. Add an alias on your local repository to github to avoid typing:
Code Block |
---|
git remotes add github https://github.com/<your_user>/kafka.git
|
Now you can push either to origin or to github.
Doing Work
1. You can create a branch named xyz in your local repository and check it out
Code Block |
---|
git checkout -b xyz remotes/origin/trunk
|
2. To set up a second machine to work on you can clone the github url.
3. To save your branch to your github repo do
Code Block |
---|
git push github xyz
|
4. To pull these changes onto the other machine where you have a copy of the repository you can do:
Code Block |
---|
git fetch github
git checkout xyz
git merge remotes/github/xyz
|
Overview
The Kafka project development ecosystem involves git (for version control), JIRA (for issue tracking) and either GitHub pull requests or Review Board (for reviewing code changes made by contributors). See below for more details.
Patch Review Tool
We have moved the contribution workflow to Github pull requests. The patch review tool has been phased out. If you are submitting a new patch, please use a Github pull request. If you are still interested in learning more about it, you can find the instructions here.
Contributor and Reviewer Workflow
The process for contributing or reviewing a patch is documented in the Contributing Code Changes page.
Committer Workflow
If you are merging a patch attached to a JIRA (and not a GitHub PR), here is a suggested workflow.
Instructions on merging GitHub pull requests are here.
How to get your patches reviewed
Please ping the dev mailing list if you have a patch that needs a review and it will be added to the queue. The following (JIRA link) are issues that currently have patches available and have an assigned reviewer:
Jira | ||||||||
---|---|---|---|---|---|---|---|---|
|
Review and pushing changes back to Apache works just as before.