Page History

...

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

Casual Browsing

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

...

1. Checkout a new repository:

git clone httpsgit://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

...

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"

...

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

...

7. If things go wrong (tests fail, you find some problem, etc), you can back out:

git reset --hard HEAD
git clean -f

8. If after review and running the test you want to push the change into the Apache repo:

git push origin master

Committer Workflow

...

1. Create a branch to work on:

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

2. Implement the feature. Commit as desired to phase the work.

commit -am "<short message about progress.>"

3. Rebase as required to track the master branch.

git stash
git rebase remotes/origin/master
git stash pop

4. Run the tests. Should always rebase before testing before submitting a patch.

ant verify

5. Create a patch

git reset --soft origin/master
git commit -am "KNOX-nnn: <short, meaningful message>"
git format-patch origin/master --stdout > KNOX-nnn.patch

...

7. Push the change back to Apache. Pick one of the following:

git push

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.

...

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//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

...

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.