|
| 1 | +# How to Contribute |
| 2 | + |
| 3 | +We want your help to make Project Hydra great. |
| 4 | +There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. |
| 5 | + |
| 6 | +## Hydra Project Intellectual Property Licensing and Ownership |
| 7 | + |
| 8 | +All code contributors must have an Individual Contributor License Agreement (iCLA) on file with the Hydra Project Steering Group. |
| 9 | +If the contributor works for an institution, the institution must have a Corporate Contributor License Agreement (cCLA) on file. |
| 10 | + |
| 11 | +https://wiki.duraspace.org/display/hydra/Hydra+Project+Intellectual+Property+Licensing+and+Ownership |
| 12 | + |
| 13 | +You should also add yourself to the `CONTRIBUTORS.md` file in the root of the project. |
| 14 | + |
| 15 | +## Contribution Tasks |
| 16 | + |
| 17 | +* Reporting Issues |
| 18 | +* Making Changes |
| 19 | +* Submitting Changes |
| 20 | +* Merging Changes |
| 21 | + |
| 22 | +### Reporting Issues |
| 23 | + |
| 24 | +* Make sure you have a [GitHub account](https://github.com/signup/free) |
| 25 | +* Submit a [Github issue](./issues) by: |
| 26 | + * Clearly describing the issue |
| 27 | + * Provide a descriptive summary |
| 28 | + * Explain the expected behavior |
| 29 | + * Explain the actual behavior |
| 30 | + * Provide steps to reproduce the actual behavior |
| 31 | + |
| 32 | +### Making Changes |
| 33 | + |
| 34 | +* Fork the repository on GitHub |
| 35 | +* Create a topic branch from where you want to base your work. |
| 36 | + * This is usually the master branch. |
| 37 | + * To quickly create a topic branch based on master; `git branch fix/master/my_contribution master` |
| 38 | + * Then checkout the new branch with `git checkout fix/master/my_contribution`. |
| 39 | + * Please avoid working directly on the `master` branch. |
| 40 | + * You may find the [hub suite of commands](https://github.com/defunkt/hub) helpful |
| 41 | +* Make commits of logical units. |
| 42 | + * Your commit should include a high level description of your work in HISTORY.textile |
| 43 | +* Check for unnecessary whitespace with `git diff --check` before committing. |
| 44 | +* Make sure your commit messages are [well formed](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). |
| 45 | +* If you created an issue, you can close it by including "Closes #issue" in your commit message. See [Github's blog post for more details](https://github.com/blog/1386-closing-issues-via-commit-messages) |
| 46 | + |
| 47 | +``` |
| 48 | + Present tense short summary (50 characters or less) |
| 49 | +
|
| 50 | + More detailed description, if necessary. It should be wrapped to 72 |
| 51 | + characters. Try to be as descriptive as you can, even if you think that |
| 52 | + the commit content is obvious, it may not be obvious to others. You |
| 53 | + should add such description also if it's already present in bug tracker, |
| 54 | + it should not be necessary to visit a webpage to check the history. |
| 55 | +
|
| 56 | + Include Closes #<issue-number> when relavent. |
| 57 | +
|
| 58 | + Description can have multiple paragraphs and you can use code examples |
| 59 | + inside, just indent it with 4 spaces: |
| 60 | +
|
| 61 | + class PostsController |
| 62 | + def index |
| 63 | + respond_with Post.limit(10) |
| 64 | + end |
| 65 | + end |
| 66 | +
|
| 67 | + You can also add bullet points: |
| 68 | +
|
| 69 | + - you can use dashes or asterisks |
| 70 | +
|
| 71 | + - also, try to indent next line of a point for readability, if it's too |
| 72 | + long to fit in 72 characters |
| 73 | +``` |
| 74 | + |
| 75 | +* Make sure you have added the necessary tests for your changes. |
| 76 | +* Run _all_ the tests to assure nothing else was accidentally broken. |
| 77 | +* When you are ready to submit a pull request |
| 78 | + |
| 79 | +### Submitting Changes |
| 80 | + |
| 81 | +* Read the article ["Using Pull Requests"](https://help.github.com/articles/using-pull-requests) on GitHub. |
| 82 | +* Make sure your branch is up to date with its parent branch (i.e. master) |
| 83 | + * `git checkout master` |
| 84 | + * `git pull --rebase` |
| 85 | + * `git checkout <your-branch>` |
| 86 | + * `git rebase master` |
| 87 | + * It is likely a good idea to run your tests again. |
| 88 | +* Squash the commits for your branch into one commit |
| 89 | + * `git rebase --interactive HEAD~<number-of-commits>` ([See Github help](https://help.github.com/articles/interactive-rebase)) |
| 90 | + * To determine the number of commits on your branch: `git log master..<your-branch> --oneline | wc -l` |
| 91 | + * Squashing your branch's changes into one commit is "good form" and helps the person merging your request to see everything that is going on. |
| 92 | +* Push your changes to a topic branch in your fork of the repository. |
| 93 | +* Submit a pull request from your fork to the project. |
| 94 | + |
| 95 | +### Merging Changes |
| 96 | + |
| 97 | +* It is considered "poor from" to merge your own request. |
| 98 | +* Please take the time to review the changes and get a sense of what is being changed. Things to consider: |
| 99 | + * Does the commit message explain what is going on? |
| 100 | + * Does the code changes have tests? _Not all changes need new tests, some changes are refactorings_ |
| 101 | + * Does the commit contain more than it should? Are two separate concerns being addressed in one commit? |
| 102 | + * Did the Travis tests complete successfully? |
| 103 | +* If you are uncertain, bring other contributors into the conversation by creating a comment that includes their @username. |
| 104 | +* If you like the pull request, but want others to chime in, create a +1 comment and tag a user. |
| 105 | + |
| 106 | +# Additional Resources |
| 107 | + |
| 108 | +* [General GitHub documentation](http://help.github.com/) |
| 109 | +* [GitHub pull request documentation](http://help.github.com/send-pull-requests/) |
| 110 | +* [Pro Git](http://git-scm.com/book) is both a free and excellent book about Git. |
| 111 | +* [A Git Config for Contributing](http://ndlib.github.io/practices/my-typical-per-project-git-config/) |
0 commit comments