|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Thanks for taking the time to contribute! |
| 4 | + |
| 5 | +All types of contributions are encouraged and valued. Please try to read the |
| 6 | +relevant sections in this document before making your contribution. It will |
| 7 | +make it a lot easier for us maintainers and smooth out the experience for all |
| 8 | +involved. The community looks forward to your contributions. |
| 9 | + |
| 10 | +> And if you like the project, but just don't have time to contribute, that's |
| 11 | +> fine. There are other easy ways to support the project and show your |
| 12 | +> appreciation, which we would also be very happy about: |
| 13 | +> - Star the project |
| 14 | +> - Post about it on social media |
| 15 | +> - Refer this project in your own project's README |
| 16 | +> - Mention the project at local meetups and tell your friends/colleagues |
| 17 | +
|
| 18 | +## I Have a Question |
| 19 | + |
| 20 | +> Please ensure you've already read the available |
| 21 | +> [Documentation](https://developers.oxylabs.io/), which may have |
| 22 | +> answered your question. |
| 23 | +
|
| 24 | +Before you ask a question, it is best to search for existing |
| 25 | +[Issues](https://github.com/mslmio/oxylabs-sdk-python/issues) that might help you. In |
| 26 | +case you have found a suitable issue and still need clarification, you can |
| 27 | +write your question in this issue. It is also advisable to search the internet |
| 28 | +for answers first. |
| 29 | + |
| 30 | +If you then still feel the need to ask a question and need clarification, we |
| 31 | +recommend the following: |
| 32 | + |
| 33 | +- Open an [Issue](https://github.com/mslmio/oxylabs-sdk-python/issues/new). |
| 34 | +- Provide as much context as you can about what you're running into. |
| 35 | +- Provide project and platform versions (nodejs, npm, etc), depending on what |
| 36 | + seems relevant. |
| 37 | + |
| 38 | +We will then take care of the issue as soon as possible. |
| 39 | + |
| 40 | +## I Want To Contribute |
| 41 | + |
| 42 | +> ### Legal Notice |
| 43 | +> |
| 44 | +> When contributing to this project, you must agree that you have authored 100% |
| 45 | +> of the content, that you have the necessary rights to the content and that |
| 46 | +> the content you contribute may be provided under the project licence. |
| 47 | +
|
| 48 | +### Reporting Bugs |
| 49 | + |
| 50 | +#### Before Submitting a Bug Report |
| 51 | + |
| 52 | +A good bug report shouldn't leave others needing to chase you up for more |
| 53 | +information. Therefore, we ask you to investigate carefully, collect |
| 54 | +information and describe the issue in detail in your report. Please complete |
| 55 | +the following steps in advance to help us fix any potential bug as fast as |
| 56 | +possible. |
| 57 | + |
| 58 | +- Make sure that you are using the latest version. |
| 59 | +- Determine if your bug is really a bug and not an error on your side e.g. |
| 60 | + using incompatible environment components/versions (Make sure that you have |
| 61 | + read the |
| 62 | + [documentation](https://developers.oxylabs.io/). If you |
| 63 | + are looking for support, you might want to check [this |
| 64 | + section](#i-have-a-question)). |
| 65 | +- To see if other users have experienced (and potentially already solved) the |
| 66 | + same issue you are having, check if there is not already a bug report |
| 67 | + existing for your bug or error in the [bug |
| 68 | + tracker](https://github.com/mslmio/oxylabs-sdk-python/issues?q=label%3Abug). |
| 69 | +- Also make sure to search the internet (including Stack Overflow) to see if |
| 70 | + users outside of the GitHub community have discussed the issue. |
| 71 | +- Collect information about the bug: |
| 72 | +- Stack trace (Traceback) |
| 73 | +- OS, Platform and Version (Windows, Linux, macOS, x86, ARM) |
| 74 | +- Version of the interpreter, compiler, SDK, runtime environment, package |
| 75 | + manager, depending on what seems relevant. |
| 76 | +- Possibly your input and the output |
| 77 | +- Can you reliably reproduce the issue? And can you also reproduce it with |
| 78 | + older versions? |
| 79 | + |
| 80 | +#### How Do I Submit a Good Bug Report? |
| 81 | + |
| 82 | +> You must never report security related issues, vulnerabilities or bugs |
| 83 | +> including sensitive information to the issue tracker, or elsewhere in public. |
| 84 | +> Instead sensitive bugs must be sent by email to . |
| 85 | +
|
| 86 | +We use GitHub issues to track bugs and errors. If you run into an issue with the project: |
| 87 | + |
| 88 | +- Open an [Issue](https://github.com/mslmio/oxylabs-sdk-python/issues/new). (Since we |
| 89 | + can't be sure at this point whether it is a bug or not, we ask you not to |
| 90 | + talk about a bug yet and not to label the issue.) |
| 91 | +- Explain the behavior you would expect and the actual behavior. |
| 92 | +- Please provide as much context as possible and describe the *reproduction |
| 93 | + steps* that someone else can follow to recreate the issue on their own. This |
| 94 | + usually includes your code. For good bug reports you should isolate the |
| 95 | + problem and create a reduced test case. |
| 96 | +- Provide the information you collected in the previous section. |
| 97 | + |
| 98 | +Once it's filed: |
| 99 | + |
| 100 | +- The project team will label the issue accordingly. |
| 101 | +- A team member will try to reproduce the issue with your provided steps. If |
| 102 | + there are no reproduction steps or no obvious way to reproduce the issue, the |
| 103 | + team will ask you for those steps and mark the issue as `needs-repro`. Bugs |
| 104 | + with the `needs-repro` tag will not be addressed until they are reproduced. |
| 105 | +- If the team is able to reproduce the issue, it will be marked `needs-fix`, as |
| 106 | + well as possibly other tags (such as `critical`), and the issue will be left |
| 107 | + to be [implemented by someone](#your-first-code-contribution). |
| 108 | + |
| 109 | +### Suggesting Enhancements |
| 110 | + |
| 111 | +This section guides you through submitting an enhancement suggestion, |
| 112 | +**including completely new features and minor improvements to existing |
| 113 | +functionality**. Following these guidelines will help maintainers and the |
| 114 | +community to understand your suggestion and find related suggestions. |
| 115 | + |
| 116 | +#### Before Submitting an Enhancement |
| 117 | + |
| 118 | +- Make sure that you are using the latest version. |
| 119 | +- Read the [documentation](https://developers.oxylabs.io/) carefully and |
| 120 | + find out if the functionality is already covered, maybe by an individual |
| 121 | + configuration. |
| 122 | +- Perform a [search](https://github.com/mslmio/oxylabs-sdk-python/issues) to see if |
| 123 | + the enhancement has already been suggested. If it has, add a comment to the |
| 124 | + existing issue instead of opening a new one. |
| 125 | +- Find out whether your idea fits with the scope and aims of the project. It's |
| 126 | + up to you to make a strong case to convince the project's developers of the |
| 127 | + merits of this feature. Keep in mind that we want features that will be |
| 128 | + useful to the majority of our users and not just a small subset. If you're |
| 129 | + just targeting a minority of users, consider writing an add-on/plugin |
| 130 | + library. |
| 131 | + |
| 132 | +#### How Do I Submit a Good Enhancement Suggestion? |
| 133 | + |
| 134 | +Enhancement suggestions are tracked as [GitHub issues](https://github.com/mslmio/oxylabs-sdk-python/issues). |
| 135 | + |
| 136 | +- Use a **clear and descriptive title** for the issue to identify the |
| 137 | + suggestion. |
| 138 | +- Provide a **step-by-step description of the suggested enhancement** in as |
| 139 | + many details as possible. |
| 140 | +- **Describe the current behavior** and **explain which behavior you expected |
| 141 | + to see instead** and why. At this point you can also tell which alternatives |
| 142 | + do not work for you. |
| 143 | +- You may want to **include screenshots or screen recordings** which help you |
| 144 | + demonstrate the steps or point out the part which the suggestion is related |
| 145 | + to. |
| 146 | +- **Explain why this enhancement would be useful** to most users. You may also |
| 147 | + want to point out the other projects that solved it better and which could |
| 148 | + serve as inspiration. |
| 149 | + |
| 150 | +## Security Issue Notifications |
| 151 | + |
| 152 | +Please see Oxylabs' [Vulnerability Disclosure |
| 153 | +Policy](https://oxylabs.io/legal/vulnerability-disclosure-policy) for details. |
0 commit comments