1########################### 2Contributing to APScheduler 3########################### 4 5If you wish to add a feature or fix a bug in APScheduler, you need to follow certain procedures and 6rules to get your changes accepted. This is to maintain the high quality of the code base. 7 8 9Contribution Process 10==================== 11 121. Fork the project on Github 132. Clone the fork to your local machine 143. Make the changes to the project 154. Run the test suite with tox (if you changed any code) 165. Repeat steps 3-4 until the test suite passes 176. Commit if you haven't already 187. Push the changes to your Github fork 198. Make a pull request on Github 20 21There is no need to update the change log -- this will be done prior to the next release at the 22latest. Should the test suite fail even before your changes (which should be rare), make sure 23you're at least not adding to the failures. 24 25 26Development Dependencies 27======================== 28 29To fully run the test suite, you will need at least: 30 31 * A MongoDB server 32 * A Redis server 33 * A Zookeeper server 34 35For other dependencies, it's best to look in tox.ini and install what is appropriate for the Python 36version you're using. 37 38 39Code Style 40========== 41 42This project uses PEP 8 rules with its maximum allowed column limit of 99 characters. 43This limit applies to all text files (source code, tests, documentation). 44In particular, remember to group the imports correctly (standard library imports first, third party 45libs second, project libraries third, conditional imports last). The PEP 8 checker does not check 46for this. If in doubt, just follow the surrounding code style as closely as possible. 47 48 49Testing 50======= 51 52Running the test suite is done using the tox_ utility. This will test the code base against all 53supported Python versions and performs some code quality checks using flake8_ as well. 54 55Some tests require the presence of external services (in practice, database servers). To help with 56that, there is a docker-compose_ configuration included. Running ``docker-compose up -d`` will 57start all the necessary services for the tests to work. 58 59Any nontrivial code changes must be accompanied with the appropriate tests. The tests should not 60only maintain the coverage, but should test any new functionality or bug fixes reasonably well. 61If you're fixing a bug, first make sure you have a test which fails against the unpatched codebase 62and succeeds against the fixed version. Naturally, the test suite has to pass on every Python 63version. If setting up all the required Python interpreters seems like too much trouble, make sure 64that it at least passes on the lowest supported versions of both Python 2 and 3. The full test 65suite is always run against each pull request, but it's a good idea to run the tests locally first. 66 67.. _tox: https://tox.readthedocs.io/ 68.. _flake8: http://flake8.pycqa.org/ 69.. _docker-compose: https://docs.docker.com/compose/ 70