Contribution Processes

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

Code Change Governing Policy

Apache Knox follows the Commit-Then-Review policy as defined in: http://www.apache.org/foundation/glossary.html

Commit-Then-Review

(Often abbreviated 'CTR' or 'C-T-R'.) A policy governing code changes which permits developers to make changes at will, with the possibility of being retroactively vetoed. C-T-R is an application of decision making through lazy consensus. The C-T-R model is useful in rapid-prototyping environments, but because of the lack of mandatory review it may permit more bugs through in daily practice than the R-T-C alternative. Compare R-T-C , and see the description of the voting process.

Acknowledging the potential negative aspects of not mandating a review for every commit, we have a short set of guidelines and a notification mechanism for ensuring the rapid development that CTR affords the community while providing communication and attention to review comments which are all important to the Knox community.

The following guidelines are prescribed for committers on the Apache Knox project and should be considered for each change commit:

Guidelines

1. For any patches that make fundamental, architectural or security related changes - committers should solicit feedback on the design and document it clearly in an document attached to JIRA or wiki linked to from the JIRA
2. For any patches that are extensions to existing patterns for features - such as adding new service API support, the committer may commit freely - given sufficient tests and documentation (to the committer's discretion)
3. For any patches that are simple bug fixes, the committer may commit freely

Notification

In order to draw attention to review topics the use of the [REVIEW] tag in an email subject will be used for:

1. Reviews from community members post commit - we will use an email with a [REVIEW] tag to indicate that comments are being provided for a merged change and that it needs attention. Committers must review such comments and assess whether they should manifest in:
   1. New JIRAs to address the review comments
   2. A veto discussion and revert upon justification - see the veto process definition
   3. Further documentation is needed
   4. Any combination of above
2. The [REVIEW] tag may also be used by committers or any contributor in order to solicit feedback on design or technical details from the community at large - see guideline #1 above.

Casual Browsing

https://git-wip-us.apache.org/repos/asf?p=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 git://git.apache.org/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 (https://git-wip-us.apache.org/repos/asf/knox.git).

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. If after review and running the test you want to push the change into the Apache repo:

git push origin master

Committer Workflow

If you have commit access on the Apache repository (https://git-wip-us.apache.org/repos/asf/knox.git) then you will not be applying patches in the manner described in the reviewer workflow.
Instead, once your patch is ready, you will check it in yourself as follows:

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 prior to submitting a patch.

ant verify

5. Create a patch, if desired. Note that commit messages should include the issue identifier and the issue title.

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

6. Post the change patch file to JIRA and optionally get it reviewed.

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

git push

Committer Workflow using Git Branches

If you are working on a sizable set of code, for instance, implementing a significant feature, then it is recommended to use a Git remote branch. This will not only help backup your code but also ensure the master branch is never in an unstable state. Also, using a branch will make for easy code reviews and collaboration. 

The workflow for creating a remote branch and using it is the following (presuming that you have done a git clone and are in the master branch) :

1. Create a local branch from master:

git checkout -b KNOX-nnn

2. Push the local branch remote and setup remote tracking

git push -u origin KNOX-nnn

3. Implement the feature and commit and push as desired. Note that commit messages should include the issue identifier and the issue title.

git commit -am "<short message about commit>"
git push

4. To update the branch from master at any time

git pull --rebase origin master

5. To merge the branch back into master, first switch to the master branch and then merge.

git checkout master
git merge KNOX-nnn
git push

6. After all code has been merged and the branch is no longer needed, it can be deleted remotely with:

git push origin :KNOX-nnn

To delete the branch locally

git branch -d KNOX-nnn

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 Knox (if you haven't already):

git clone git://git.apache.org/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.

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.

Documentation Contributor Workflow

All of the documentation is maintained in a separate SVN repository to facilitate independent updates.

1. Checkout the SVN repository.

svn checkout https://svn.apache.org/repos/asf/knox knox-site
cd knox-site

2. Edit site or documentation files.  Note that there are no version branches in the SVN repo.  Each version of the guides are maintained in separate directories identified by {version} in the example command blow.  In addition, most of the guides are in Markdown format and are broken into multiple sections as indicated by {section}.md in the command below.  These fils can be edited with the tool of your choice vi is only used as an example.

vi trunk/books/{version}/{section}.md

3. Generate the new site and review.  The command below should be run from the root of the product.  The 'review' target causes the local site to be launched in a browser so that you can review the generation result.

ant generate review

4. If you're only creating a patch, then remove any changes to the generated site.  Those changes will be regenerated by the committer as part of committing the patch.  If you don't do this it makes it patch review process very difficult.  We recommend naming the patch using the JIRA ID.  Upload the patch to the JIRA and request review from a committer.

svn revert --recursive site
svn diff > KNOX-nnn.patch

5. If you're committing changes, then DO NOT revert the generated site content. Commit all the changes.

svn ci <modified_files> -m "Change comment"