Contribution Process

Special thanks to Apache Kafka from which most of this documented process was blatently copied.

Casual Browsing

https://git-wip-us.apache.org/repos/asf?p=incubator-knox.git

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, KNOX-nnn:

1. Checkout a new repository:

git clone https://git-wip-us.apache.org/repos/asf/incubator-knox.git

2. Create and checkout a branch to work in:

git checkout -b KNOX-nnn remote/origin/master

3. Do some work on this branch and periodically checkin locally:

git commit -a

4. When done (or periodically) rebase your branch to take any changes from trunk:

git pull --rebase origin master

5. Make a patch containing your work and upload it to JIRA:

git format-patch master --stdout > KNOX-nnn.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:

git config --global user.name "Joe Coder"
git config --global user.email "jcoder@fake.org"

Reviewer Workflow

This assumes you already have a copy of the repository.

1. Make sure your code is up-to-date:

git fetch

2. Checkout the destination branch:

git checkout master

3. See what the patch will do:

git apply --stat KNOX-nnn.patch

4. See that the patch will apply cleanly (otherwise prod the contributor to rebase):

git apply --check KNOX-nnn.patch

6. Apply the patch to trunk

git am --signoff < KNOX-nnn.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.

patch -p1 < KNOX-nnn.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:

git reset --hard HEAD
git clean -f

8. Push the change back to Apache:

git push origin master

Committer 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:

1. Create a branch to work on:

git fetch
git checkout -b xyz remotes/origin/trunk

2. Implement the feature.

3. Rebase

git rebase remotes/origin/trunk

4. Post the change to JIRA and get it reviewed.

5. 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:

# Assuming trunk is up-to-date with origin
git checkout master
git merge --squash xyz
git commit -am "KNOX-nnn xyz feature; reviewed by <reviewers>"
git push origin master

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):

6. From feature branch KNOX-nnn

git push origin trunk

h2. 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.

h3. Setting Up

1. As in the other workflows begin by checking out Knox (if you haven't already):

git clone https://git-wip-us.apache.org/repos/asf/incubator-knox.git

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 Knox repo ([https://github.com/apache/knox]) which creates a repo [https://github.com/<github_username>/knox]
3. Add an alias on your local repository to github to avoid typing:

git remotes add github https://github.com/<github_username>/knox.git

Now you can push either to origin or to github.

h3. Doing Work

1. You can create a branch named KNOX-nnn in your local repository and check it out

git checkout -b KNOX-nnn remotes/origin/master

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

git push github KNOX-nnn

4. To pull these changes onto the other machine where you have a copy of the repository you can do:

git fetch github
git checkout KNOX-nnn
git merge remotes/github/KNOX-nnn

Review and pushing changes back to Apache works just as before.