Contributions in code to the
asyncstdlib library are highly welcome!
We describe below how you can create a pull request and have it merged in.
Before you start writing code, please create a new issue first and discuss what you intend to implement. It can well be that somebody else is already working on it, or that the suggested interface of your code needs to be changed in order to be consistent with the rest of the library etc.
We develop using GitHub’s forks:
Create a fork of the repository to your Github account,
Clone the forked repository locally,
Write code in a branch of your local repository,
Push the branch to the remote forked repository, and finally
Create the pull request (by using Github UI on your forked repository).
Please see the page on GitHub’s forks for more detailed instruction.
Also see this page on how to update your fork to the upstream repository.
To set up the development environment on your computer, change to the local repository and:
Create the virtual environment in
python -m venv venv
Activate the virtual environment, on Windows:
or on Linux/Mac:
Install the test dependencies and documentation dependencies of
pip3 install .[test,doc]
Write the Code¶
Now you can implement your feature.
Make sure you also write the corresponding unit tests in the
We perform the following battery of pre-commit checks:
Check the code style with flake8:
python -m flake8
Check the code formatting with Black:
python -m black --target-version py36 --diff --check asyncstdlib unittests
You can also automatically format the code with:
python -m black --target-version py36 asyncstdlib unittests
Run unit tests and measure the code coverage by:
python -m coverage run -m pytest
The HTML report of the coverage can be generated by:
The report on coverage is stored in the
Make sure that your test provide a full coverage of your code.
Once you are finished with the implementation, do not forget to document your
code in the directory
We use Sphinx to render the documentation to HTML.
To generate the documentation, change to
docs/ and execute, on Windows:
or on Linux/Mac:
The documentation is available in
Commit your Changes¶
Make a single commit for each self-contained change.
Write the the commit messages in past tense and starting with a lower case. Please observe the maximum line length of 72 characters for the body.
Here are a couple of examples of commit messages:
Push the commit to your remote fork and create the pull request (see the documentation on Github’s forks for more details).
Please put the title of your pull request in imperative mood and first upper case.
Here is an example of a title of the pull request:
We will review your pull request as soon as possible. If changes are requested, please create new commits to address the review comments.
Once the pull request is approved, we will finally squash the individual commits and merge it into the main branch.