|
| 1 | +Contributing |
| 2 | +============ |
| 3 | + |
| 4 | +Introduction |
| 5 | +------------ |
| 6 | + |
| 7 | +First off, thank you for considering contributing to redis-py. We value community contributions! |
| 8 | + |
| 9 | +Contributions We Need |
| 10 | +---------------------- |
| 11 | + |
| 12 | +You may already know what you want to contribute -- a fix for a bug you encountered, or a new feature your team wants to use. |
| 13 | + |
| 14 | +If you don't know what to contribute, keep an open mind! Improving documentation, bug triaging, and writing tutorials are all examples of helpful contributions that mean less work for you. |
| 15 | + |
| 16 | +Your First Contribution |
| 17 | +----------------------- |
| 18 | +Unsure where to begin contributing? You can start by looking through `help-wanted issues <https://github.com/andymccurdy/redis-py/issues?q=is%3Aopen+is%3Aissue+label%3ahelp-wanted>`_. |
| 19 | + |
| 20 | +Never contributed to open source before? Here are a couple of friendly tutorials: |
| 21 | + |
| 22 | +- http://makeapullrequest.com/ |
| 23 | +- http://www.firsttimersonly.com/ |
| 24 | + |
| 25 | +Getting Started |
| 26 | +--------------- |
| 27 | + |
| 28 | +Here's how to get started with your code contribution: |
| 29 | + |
| 30 | +1. Create your own fork of redis-py |
| 31 | +2. Do the changes in your fork |
| 32 | +3. If you need a development environment, run ``make dev`` |
| 33 | +4. While developing, make sure the tests pass by running ``make test`` |
| 34 | +5. If you like the change and think the project could use it, send a pull request |
| 35 | + |
| 36 | +The Development Environment |
| 37 | +--------------------------- |
| 38 | + |
| 39 | +Running ``make dev`` will create a Docker-based development environment that starts the following containers: |
| 40 | + |
| 41 | +* A master Redis node |
| 42 | +* A slave Redis node |
| 43 | +* Three sentinel Redis nodes |
| 44 | +* A test container |
| 45 | + |
| 46 | +The slave is a replica of the master node, using the `leader-follower replication <https://redis.io/topics/replication>`_ feature. |
| 47 | + |
| 48 | +The sentinels monitor the master node in a `sentinel high-availability configuration <https://redis.io/topics/sentinel>`_. |
| 49 | + |
| 50 | +Meanwhile, the `test` container hosts the code from your checkout of ``redis-py`` and allows running tests against many Python versions. |
| 51 | + |
| 52 | +Docker Tips |
| 53 | +^^^^^^^^^^^ |
| 54 | + |
| 55 | +Following are a few tips that can help you work with the Docker-based development environment. |
| 56 | + |
| 57 | +To get a bash shell inside of a container: |
| 58 | + |
| 59 | +``$ docker-compose run <service> /bin/bash`` |
| 60 | + |
| 61 | +**Note**: The term "service" refers to the "services" defined in the ``docker-compose.yml`` file: "master", "slave", "sentinel_1", "sentinel_2", "sentinel_3", "test". |
| 62 | + |
| 63 | +Containers run a minimal Debian image that probably lacks tools you want to use. To install packages, first get a bash session (see previous tip) and then run: |
| 64 | + |
| 65 | +``$ apt update && apt install <package>`` |
| 66 | + |
| 67 | +You can see the combined logging output of all containers like this: |
| 68 | + |
| 69 | +``$ docker-compose logs`` |
| 70 | + |
| 71 | +The command `make test` runs all tests in all tested Python environments. To run the tests in a single environment, like Python 3.6, use a command like this: |
| 72 | + |
| 73 | +``$ docker-compose run test tox -e py36 -- --redis-url=redis://master:6379/9`` |
| 74 | + |
| 75 | +Here, the flag ``-e py36`` runs tests against the Python 3.6 tox environment. And note from the example that whenever you run tests like this, instead of using `make test`, you need to pass ``-- --redis-url=redis://master:6379/9``. This points the tests at the "master" container. |
| 76 | + |
| 77 | +Our test suite uses ``pytest``. You can run a specific test suite against a specific Python version like this: |
| 78 | + |
| 79 | +``$ docker-compose run test tox -e py36 -- --redis-url=redis://master:6379/9 tests/test_commands.py`` |
| 80 | + |
| 81 | +Troubleshooting |
| 82 | +^^^^^^^^^^^^^^^ |
| 83 | +If you get any errors when running ``make dev`` or ``make test``, make sure that you |
| 84 | +are using supported versions of Docker and docker-compose. |
| 85 | + |
| 86 | +The included Dockerfiles and docker-compose.yml file work with the following |
| 87 | +versions of Docker and docker-compose: |
| 88 | + |
| 89 | +* Docker 19.03.12 |
| 90 | +* docker-compose 1.26.2 |
| 91 | + |
| 92 | +How to Report a Bug |
| 93 | +------------------- |
| 94 | + |
| 95 | +Security Vulnerabilities |
| 96 | +^^^^^^^^^^^^^^^^^^^^^^^^ |
| 97 | + |
| 98 | +** NOTE**: If you find a security vulnerability, do NOT open an issue. Email Andy McCurdy ( [email protected]) instead. |
| 99 | + |
| 100 | +In order to determine whether you are dealing with a security issue, ask yourself these two questions: |
| 101 | + |
| 102 | +* Can I access something that's not mine, or something I shouldn't have access to? |
| 103 | +* Can I disable something for other people? |
| 104 | + |
| 105 | +If the answer to either of those two questions are "yes", then you're probably dealing with a security issue. Note that even if you answer "no" to both questions, you may still be dealing with a security issue, so if you're unsure, just email Andy at [email protected]. |
| 106 | + |
| 107 | +Everything Else |
| 108 | +^^^^^^^^^^^^^^^ |
| 109 | + |
| 110 | +When filing an issue, make sure to answer these five questions: |
| 111 | + |
| 112 | +1. What version of redis-py are you using? |
| 113 | +2. What version of redis are you using? |
| 114 | +3. What did you do? |
| 115 | +4. What did you expect to see? |
| 116 | +5. What did you see instead? |
| 117 | + |
| 118 | +How to Suggest a Feature or Enhancement |
| 119 | +--------------------------------------- |
| 120 | + |
| 121 | +If you'd like to contribute a new feature, make sure you check our issue list to see if someone has already proposed it. Work may already be under way on the feature you want -- or we may have rejected a feature like it already. |
| 122 | + |
| 123 | +If you don't see anything, open a new issue that describes the feature you would like and how it should work. |
| 124 | + |
| 125 | +Code Review Process |
| 126 | +------------------- |
| 127 | + |
| 128 | +The core team looks at Pull Requests on a regular basis. We will give feedback as as soon as possible. After feedback, we expect a response within two weeks. After that time, we may close your PR if it isn't showing any activity. |
0 commit comments