|
| 1 | +# Contributing to `twilio-node` |
| 2 | + |
| 3 | +We'd love for you to contribute to our source code and to make `twilio-node` |
| 4 | +even better than it is today! Here are the guidelines we'd like you to follow: |
| 5 | + |
| 6 | + - [Code of Conduct](#coc) |
| 7 | + - [Question or Problem?](#question) |
| 8 | + - [Issues and Bugs](#issue) |
| 9 | + - [Feature Requests](#feature) |
| 10 | + - [Documentation fixes](#docs) |
| 11 | + - [Submission Guidelines](#submit) |
| 12 | + - [Coding Rules](#rules) |
| 13 | + |
| 14 | +## <a name="coc"></a> Code of Conduct |
| 15 | + |
| 16 | +Help us keep `twilio-node` open and inclusive. Please be kind to and considerate |
| 17 | +of other developers, as we all have the same goal: make `twilio-node` as good as |
| 18 | +it can be. |
| 19 | + |
| 20 | +## <a name="question"></a> Got an API/Product Question or Problem? |
| 21 | + |
| 22 | +If you have questions about how to use `twilio-node`, please see our |
| 23 | +[docs][docs-link], and if you don't find the answer there, please contact |
| 24 | +[help@twilio.com](mailto:help@twilio.com) with any issues you have. |
| 25 | + |
| 26 | +## <a name="issue"></a> Found an Issue? |
| 27 | + |
| 28 | +If you find a bug in the source code or a mistake in the documentation, you can |
| 29 | +help us by submitting [an issue][issue-link]. If the file in which the error |
| 30 | +exists has this header: |
| 31 | +``` |
| 32 | +""" |
| 33 | +This code was generated by |
| 34 | +\ / _ _ _| _ _ |
| 35 | + | (_)\/(_)(_|\/| |(/_ v1.0.0 |
| 36 | + / / |
| 37 | +""" |
| 38 | +``` |
| 39 | +then it is a generated file and the change will need to be made by us, but |
| 40 | +submitting an issue will help us track it and keep you up-to-date. If the file |
| 41 | +isn't generated, you can help us out even more by submitting a Pull Request with |
| 42 | +a fix. |
| 43 | + |
| 44 | +**Please see the [Submission Guidelines](#submit) below.** |
| 45 | + |
| 46 | +## <a name="feature"></a> Want a Feature? |
| 47 | + |
| 48 | +You can request a new feature by submitting an issue to our |
| 49 | +[GitHub Repository][github]. If you would like to implement a new feature then |
| 50 | +consider what kind of change it is: |
| 51 | + |
| 52 | +* **Major Changes** that you wish to contribute to the project should be |
| 53 | + discussed first with `twilio-node` contributors in an issue or pull request so |
| 54 | + that we can develop a proper solution and better coordinate our efforts, |
| 55 | + prevent duplication of work, and help you to craft the change so that it is |
| 56 | + successfully accepted into the project. |
| 57 | +* **Small Changes** can be crafted and submitted to the |
| 58 | + [GitHub Repository][github] as a Pull Request. |
| 59 | + |
| 60 | +## <a name="docs"></a> Want a Doc Fix? |
| 61 | + |
| 62 | +If you want to help improve the docs in the helper library, it's a good idea to |
| 63 | +let others know what you're working on to minimize duplication of effort. Create |
| 64 | +a new issue (or comment on a related existing one) to let others know what |
| 65 | +you're working on. |
| 66 | + |
| 67 | +For large fixes, please build and test the documentation before submitting the |
| 68 | +PR to be sure you haven't accidentally introduced layout or formatting issues. |
| 69 | + |
| 70 | +If you want to help improve the docs at |
| 71 | +[https://www.twilio.com/docs/libraries/node][docs-link], please contact |
| 72 | +[help@twilio.com](mailto:help@twilio.com). |
| 73 | + |
| 74 | +## <a name="submit"></a> Submission Guidelines |
| 75 | + |
| 76 | +### Submitting an Issue |
| 77 | +Before you submit your issue search the archive, maybe your question was already |
| 78 | +answered. |
| 79 | + |
| 80 | +If your issue appears to be a bug, and hasn't been reported, open a new issue. |
| 81 | +Help us to maximize the effort we can spend fixing issues and adding new |
| 82 | +features by not reporting duplicate issues. Providing the following information |
| 83 | +will increase the chances of your issue being dealt with quickly: |
| 84 | + |
| 85 | +* **Overview of the Issue** - if an error is being thrown a non-minified stack |
| 86 | + trace helps |
| 87 | +* **Motivation for or Use Case** - explain why this is a bug for you |
| 88 | +* **`twilio-node` Version(s)** - is it a regression? |
| 89 | +* **Operating System (if relevant)** - is this a problem with all systems or |
| 90 | + only specific ones? |
| 91 | +* **Reproduce the Error** - provide an isolated code snippet or an unambiguous |
| 92 | + set of steps. |
| 93 | +* **Related Issues** - has a similar issue been reported before? |
| 94 | +* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point |
| 95 | + to what might be causing the problem (line of code or commit) |
| 96 | + |
| 97 | +**If you get help, help others. Good karma rules!** |
| 98 | + |
| 99 | +### Submitting a Pull Request |
| 100 | +Before you submit your pull request consider the following guidelines: |
| 101 | + |
| 102 | +* Search [GitHub][github] for an open or closed Pull Request that relates to |
| 103 | + your submission. You don't want to duplicate effort. |
| 104 | +* Make your changes in a new git branch: |
| 105 | + |
| 106 | + ```shell |
| 107 | + git checkout -b my-fix-branch master |
| 108 | + ``` |
| 109 | + |
| 110 | +* Create your patch, **including appropriate test cases**. |
| 111 | +* Follow our [Coding Rules](#rules). |
| 112 | +* Run the full `twilio-node` test suite (aliased by `make test`), and ensure |
| 113 | + that all tests pass. |
| 114 | +* Commit your changes using a descriptive commit message. |
| 115 | + |
| 116 | + ```shell |
| 117 | + git commit -a |
| 118 | + ``` |
| 119 | + Note: the optional commit `-a` command line option will automatically "add" |
| 120 | + and "rm" edited files. |
| 121 | + |
| 122 | +* Build your changes locally to ensure all the tests pass: |
| 123 | + |
| 124 | + ```shell |
| 125 | + make test |
| 126 | + ``` |
| 127 | + |
| 128 | +* Push your branch to GitHub: |
| 129 | + |
| 130 | + ```shell |
| 131 | + git push origin my-fix-branch |
| 132 | + ``` |
| 133 | + |
| 134 | +In GitHub, send a pull request to `twilio-node:master`. |
| 135 | +If we suggest changes, then: |
| 136 | + |
| 137 | +* Make the required updates. |
| 138 | +* Re-run the `twilio-node` test suite to ensure tests are still passing. |
| 139 | +* Commit your changes to your branch (e.g. `my-fix-branch`). |
| 140 | +* Push the changes to your GitHub repository (this will update your Pull Request). |
| 141 | + |
| 142 | +That's it! Thank you for your contribution! |
| 143 | +
|
| 144 | +#### After your pull request is merged |
| 145 | +
|
| 146 | +After your pull request is merged, you can safely delete your branch and pull |
| 147 | +the changes from the main (upstream) repository. |
| 148 | +
|
| 149 | +## <a name="rules"></a> Coding Rules |
| 150 | +
|
| 151 | +To ensure consistency throughout the source code, keep these rules in mind as |
| 152 | +you are working: |
| 153 | +
|
| 154 | +* All features or bug fixes **must be tested** by one or more tests. |
| 155 | +* All classes and methods **must be documented**. |
| 156 | +
|
| 157 | +[docs-link]: https://www.twilio.com/docs/libraries/node |
| 158 | +[issue-link]: https://github.com/twilio/twilio-node/issues/new |
| 159 | +[github]: https://github.com/twilio/twilio-node |
0 commit comments