|
| 1 | +Contributing |
| 2 | +============ |
| 3 | + |
| 4 | +All contributions are welcome to this project. |
| 5 | + |
| 6 | +Contributor License Agreement |
| 7 | +----------------------------- |
| 8 | + |
| 9 | +Before a contribution can be merged into this project, please fill out the |
| 10 | +Contributor License Agreement (CLA) located at: |
| 11 | + |
| 12 | +http://opensource.box.com/cla |
| 13 | + |
| 14 | +To learn more about CLAs and why they are important to open source projects, |
| 15 | +please see the [Wikipedia entry][1]. |
| 16 | + |
| 17 | +How to contribute |
| 18 | +----------------- |
| 19 | + |
| 20 | +* **File an issue** - if you found a bug, want to request an enhancement, or |
| 21 | + want to implement something (bug fix or feature). |
| 22 | +* **Send a pull request** - if you want to contribute code. Please be sure to |
| 23 | + file an issue first. |
| 24 | + |
| 25 | +Pull request best practices |
| 26 | +--------------------------- |
| 27 | + |
| 28 | +Following these steps will help ensure that your pull request gets reviewed and |
| 29 | +accepted as quickly as possible. |
| 30 | + |
| 31 | +### Step 1: File an issue |
| 32 | + |
| 33 | +Before writing any code, please file an issue stating the problem you want to |
| 34 | +solve or the feature you want to implement. This allows us to give you feedback |
| 35 | +before you spend any time writing code. There may be a known limitation that |
| 36 | +can't be addressed, or a bug that has already been fixed in a different way. The |
| 37 | +issue allows us to communicate and figure out if it's worth your time to write a |
| 38 | +bunch of code for the project. |
| 39 | + |
| 40 | +### Step 2: Fork this repository in GitHub |
| 41 | + |
| 42 | +This will create your own copy of our repository. |
| 43 | + |
| 44 | +### Step 3: Add the upstream source |
| 45 | + |
| 46 | +The upstream source is the project under the Box organization on GitHub. To add |
| 47 | +an upstream source for this project, type: |
| 48 | + |
| 49 | +``` |
| 50 | +git remote add upstream [email protected]:box/box-java-sdk.git |
| 51 | +``` |
| 52 | + |
| 53 | +This will come in useful later. |
| 54 | + |
| 55 | +### Step 4: Create a feature branch |
| 56 | + |
| 57 | +Create a branch with a descriptive name, such as `add-search`. |
| 58 | + |
| 59 | +### Step 5: Push your feature branch to your fork |
| 60 | + |
| 61 | +As you develop code, continue to push code to your remote feature branch. Please |
| 62 | +make sure to include the issue number you're addressing in the body of your |
| 63 | +commit message and adhere to [standard git commit message guidelines][2]. For |
| 64 | +example: |
| 65 | + |
| 66 | +``` |
| 67 | +Add search |
| 68 | +
|
| 69 | +Introduced a new BoxSearch class that uses the /search API endpoint. |
| 70 | +
|
| 71 | +Closes #123. |
| 72 | +``` |
| 73 | + |
| 74 | +This helps us out by allowing us to track which issue your commit relates to. |
| 75 | + |
| 76 | +Keep a separate feature branch for each issue you want to address. |
| 77 | + |
| 78 | +### Step 6: Rebase |
| 79 | + |
| 80 | +Before sending a pull request, rebase against upstream, such as: |
| 81 | + |
| 82 | +``` |
| 83 | +git fetch upstream |
| 84 | +git rebase upstream/master |
| 85 | +``` |
| 86 | + |
| 87 | +This will add your changes on top of what's already in upstream, minimizing |
| 88 | +merge issues. |
| 89 | + |
| 90 | +### Step 7: Build and test your changes |
| 91 | + |
| 92 | +Make sure that the code builds and passes all unit tests by running: |
| 93 | + |
| 94 | +```bash |
| 95 | +$ gradle clean build |
| 96 | +``` |
| 97 | + |
| 98 | +### Step 8: Send the pull request |
| 99 | + |
| 100 | +Send the pull request from your feature branch to us. Be sure to include a |
| 101 | +description in your commit message (not the pull request description) that lets |
| 102 | +us know what work you did. |
| 103 | + |
| 104 | +Keep in mind that we like to see one issue addressed per pull request, as this |
| 105 | +helps keep our git history clean and we can more easily track down issues. |
| 106 | + |
| 107 | +[1]: http://en.wikipedia.org/wiki/Contributor_License_Agreement |
| 108 | +[2]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html |
0 commit comments