Special thanks to Apache Kafka from which most of this documented process was blatantly copied.
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:
2. Create and checkout a branch to work in:
3. Do some work on this branch and periodically checkin locally:
4. When done (or periodically) rebase your branch to take any changes from trunk:
5. Make a patch containing your work and upload it to JIRA:
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:
This assumes you already have a copy of the repository.
1. Make sure your code is up-to-date:
2. Checkout the destination branch:
3. See what the patch will do:
4. See that the patch will apply cleanly (otherwise prod the contributor to rebase):
6. Apply the patch to trunk
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.
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:
8. If after review and running the test you want to push the change into the Apache repo:
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:
2. Implement the feature. Commit as desired to phase the work.
3. Rebase as required to track the master branch.
4. Run the tests. Should always rebase before testing before submitting a patch.
5. Create a patch
6. Post the change patch file to JIRA and get it reviewed.
7. Push the change back to Apache. Pick one of the following:
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):
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:
Now you can push either to origin or to github.
1. You can create a branch named KNOX-nnn in your local repository and check it out
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
4. To pull these changes onto the other machine where you have a copy of the repository you can do:
Review and pushing changes back to Apache works just as before.
The Apache Knox Gateway is an effort undergoing incubation at the Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC.
Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects.
While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
Apache Knox Gateway, Apache, the Apache feather logo and the Apache Knox Gateway project logos are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
Apache Knox uses the standard Apache license.