Instructions for contributors¶
In order to make a clone of the GitHub repo: open the link and press the “Fork” button on the upper-right menu of the web page.
I hope everybody knows how to work with git and github nowadays :)
Workflow is pretty straightforward:
- Clone the GitHub repo
- Make a change
- Make sure all tests passed
- Commit changes to own aiohttp clone
- Make pull request from github page for your clone against master branch
If your PR has long history or many commits please rebase it from main repo before creating PR.
Preconditions for running aiohttp test suite¶
We expect you to use a python virtual environment to run our tests.
There are several ways to make a virtual environment.
If you like to use virtualenv please run:
$ cd aiohttp $ virtualenv --python=`which python3` venv $ . venv/bin/activate
For standard python venv:
$ cd aiohttp $ python3 -m venv venv $ . venv/bin/activate
For virtualenvwrapper (my choice):
$ cd aiohttp $ mkvirtualenv --python=`which python3` aiohttp
There are other tools like pyvenv but you know the rule of thumb now: create a python3 virtual environment and activate it.
After that please install libraries required for development:
$ pip install -r requirements-dev.txt
We also recommend to install ipdb but it’s on your own: : .. code-block:: shell
$ pip install ipdb
If you plan to use
ipdb within the test suite, execute:
$ py.test tests -s -p no:timeout command to run the tests with disabled timeout guard and output capturing.
Congratulations, you are ready to run the test suite
Run aiohttp test suite¶
After all the preconditions are met you can run tests typing the next command:
$ make test
The command at first will run the flake8 tool (sorry, we don’t accept pull requests with pep8 or pyflakes errors).
On flake8 success the tests will be run.
Please take a look on the produced output.
Any extra texts (print statements and so on) should be removed.
We are trying hard to have good test coverage; please don’t make it worse.
$ make cov
to run test suite and collect coverage information. Once the command
has finished check your coverage at the file that appears in the last
line of the output:
Please go to the link and make sure that your code change is covered.
We encourage documentation improvements.
Please before making a Pull Request about documentation changes run:
$ make doc
Once it finishes it will output the index html page
Go to the link and make sure your doc changes looks good.
sphinxcontrib-spelling for running spell
checker for documentation:
$ make doc-spelling
Unfortunately there are problems with running spell checker on MacOS X.
To run spell checker on Linux box you should install it first:
$ sudo apt-get install enchant $ pip install sphinxcontrib-spelling