|
| 1 | +# Contributing |
| 2 | + |
| 3 | +We'd love for you to contribute to our source code and to make our project even better than it is |
| 4 | +today! Here are the guidelines we'd like you to follow: |
| 5 | + |
| 6 | +* [Code of Conduct](#coc) |
| 7 | +* [Questions and Problems](#question) |
| 8 | +* [Issues and Bugs](#issue) |
| 9 | +* [Feature Requests](#feature) |
| 10 | +* [Issue Submission Guidelines](#submit) |
| 11 | +* [Pull Request Submission Guidelines](#submit-pr) |
| 12 | +* [Signing the CLA](#cla) |
| 13 | + |
| 14 | +## <a name="coc"></a> Code of Conduct |
| 15 | + |
| 16 | +Help us keep our community open-minded and inclusive. Please read and follow our [Code of Conduct][coc]. |
| 17 | + |
| 18 | +## <a name="requests"></a> Questions, Bugs, Features |
| 19 | + |
| 20 | +### <a name="question"></a> Got a Question or Problem? |
| 21 | + |
| 22 | +Do not open issues for general support questions as we want to keep GitHub issues for bug reports |
| 23 | +and feature requests. You've got much better chances of getting your question answered on dedicated |
| 24 | +support platforms, the best being [Stack Overflow][stackoverflow]. |
| 25 | + |
| 26 | +Stack Overflow is a much better place to ask questions since: |
| 27 | + |
| 28 | +- there are thousands of people willing to help on Stack Overflow |
| 29 | +- questions and answers stay available for public viewing so your question / answer might help |
| 30 | + someone else |
| 31 | +- Stack Overflow's voting system assures that the best answers are prominently visible. |
| 32 | + |
| 33 | +To save your and our time, we will systematically close all issues that are requests for general |
| 34 | +support and redirect people to the section you are reading right now. |
| 35 | + |
| 36 | +### <a name="issue"></a> Found an Issue or Bug? |
| 37 | + |
| 38 | +If you find a bug in the source code, you can help us by submitting an issue to our |
| 39 | +[GitHub Repository][github]. Even better, you can submit a Pull Request with a fix. |
| 40 | + |
| 41 | +### <a name="feature"></a> Missing a Feature? |
| 42 | + |
| 43 | +You can request a new feature by submitting an issue to our [GitHub Repository][github-issues]. |
| 44 | + |
| 45 | +If you would like to implement a new feature then consider what kind of change it is: |
| 46 | + |
| 47 | +* **Major Changes** that you wish to contribute to the project should be discussed first in an |
| 48 | + [GitHub issue][github-issues] that clearly outlines the changes and benefits of the feature. |
| 49 | +* **Small Changes** can directly be crafted and submitted to the [GitHub Repository][github] |
| 50 | + as a Pull Request. See the section about [Pull Request Submission Guidelines](#submit-pr). |
| 51 | + |
| 52 | +## <a name="submit"></a> Issue Submission Guidelines |
| 53 | + |
| 54 | +Before you submit your issue search the archive, maybe your question was already answered. |
| 55 | + |
| 56 | +If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize |
| 57 | +the effort we can spend fixing issues and adding new features, by not reporting duplicate issues. |
| 58 | + |
| 59 | +The "[new issue][github-new-issue]" form contains a number of prompts that you should fill out to |
| 60 | +make it easier to understand and categorize the issue. |
| 61 | + |
| 62 | +## <a name="submit-pr"></a> Pull Request Submission Guidelines |
| 63 | + |
| 64 | +By submitting a pull request for a code or doc contribution, you need to have the right |
| 65 | +to grant your contribution's copyright license to ProcessOne. Please check [ProcessOne CLA][cla] |
| 66 | +for details. |
| 67 | + |
| 68 | +Before you submit your pull request consider the following guidelines: |
| 69 | + |
| 70 | +* Search [GitHub][github-pr] for an open or closed Pull Request |
| 71 | + that relates to your submission. You don't want to duplicate effort. |
| 72 | +* Make your changes in a new git branch: |
| 73 | + |
| 74 | + ```shell |
| 75 | + git checkout -b my-fix-branch master |
| 76 | + ``` |
| 77 | +* Test your changes and, if relevant, expand the automated test suite. |
| 78 | +* Create your patch commit, including appropriate test cases. |
| 79 | +* If the changes affect public APIs, change or add relevant documentation. |
| 80 | +* Commit your changes using a descriptive commit message. |
| 81 | + |
| 82 | + ```shell |
| 83 | + git commit -a |
| 84 | + ``` |
| 85 | + Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. |
| 86 | + |
| 87 | +* Push your branch to GitHub: |
| 88 | + |
| 89 | + ```shell |
| 90 | + git push origin my-fix-branch |
| 91 | + ``` |
| 92 | + |
| 93 | +* In GitHub, send a pull request to `master` branch. This will trigger the continuous integration and run the test. |
| 94 | +We will also notify you if you have not yet signed the [contribution agreement][cla]. |
| 95 | + |
| 96 | +* If you find that the continunous integration has failed, look into the logs to find out |
| 97 | +if your changes caused test failures, the commit message was malformed etc. If you find that the |
| 98 | +tests failed or times out for unrelated reasons, you can ping a team member so that the build can be |
| 99 | +restarted. |
| 100 | + |
| 101 | +* If we suggest changes, then: |
| 102 | + |
| 103 | + * Make the required updates. |
| 104 | + * Test your changes and test cases. |
| 105 | + * Commit your changes to your branch (e.g. `my-fix-branch`). |
| 106 | + * Push the changes to your GitHub repository (this will update your Pull Request). |
| 107 | + |
| 108 | + You can also amend the initial commits and force push them to the branch. |
| 109 | + |
| 110 | + ```shell |
| 111 | + git rebase master -i |
| 112 | + git push origin my-fix-branch -f |
| 113 | + ``` |
| 114 | + |
| 115 | + This is generally easier to follow, but separate commits are useful if the Pull Request contains |
| 116 | + iterations that might be interesting to see side-by-side. |
| 117 | + |
| 118 | +That's it! Thank you for your contribution! |
| 119 | +
|
| 120 | +## <a name="cla"></a> Signing the Contributor License Agreement (CLA) |
| 121 | +
|
| 122 | +Upon submitting a Pull Request, we will ask you to sign our CLA if you haven't done |
| 123 | +so before. It's a quick process, we promise, and you will be able to do it all online |
| 124 | +
|
| 125 | +You can read [ProcessOne Contribution License Agreement][cla] in PDF. |
| 126 | +
|
| 127 | +This is part of the legal framework of the open-source ecosystem that adds some red tape, |
| 128 | +but protects both the contributor and the company / foundation behind the project. It also |
| 129 | +gives us the option to relicense the code with a more permissive license in the future. |
| 130 | +
|
| 131 | +
|
| 132 | +[coc]: https://github.com/processone/xmpp/blob/master/CODE_OF_CONDUCT.md |
| 133 | +[stackoverflow]: https://stackoverflow.com/ |
| 134 | +[github]: https://github.com/processone/xmpp |
| 135 | +[github-issues]: https://github.com/processone/xmpp/issues |
| 136 | +[github-new-issue]: https://github.com/processone/xmpp/issues/new |
| 137 | +[github-pr]: https://github.com/processone/xmpp/pulls |
| 138 | +[cla]: https://www.process-one.net/resources/ejabberd-cla.pdf |
| 139 | +[license]: https://github.com/processone/xmpp/blob/master/LICENSE.txt |
0 commit comments