Contribution Guidelines¶
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.
Discuss First¶
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.
Fork¶
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.
Development Environment¶
To set up the development environment on your computer, change to the local repository and:
Create the virtual environment in
venv
directory:python -m venv venv
Activate the virtual environment, on Windows:
venv\Scripts\activate
or on Linux/Mac:
. venv/bin/activate
Install the test dependencies and documentation dependencies of
asyncstdlib
:pip3 install .[test,doc]
Write the Code¶
Now you can implement your feature.
Make sure you also write the corresponding unit tests in the
unittests/
directory.
Pre-commit Checks¶
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:
coverage html
The report on coverage is stored in the
htmlcov/
directory.Make sure that your test provide a full coverage of your code.
Document¶
Once you are finished with the implementation, do not forget to document your
code in the directory docs/source/api/
.
We use Sphinx to render the documentation to HTML.
To generate the documentation, change to docs/
and execute, on Windows:
make.bat html
or on Linux/Mac:
make html
The documentation is available in docs/_build/html
.
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:
added itertools.pairwise
documented itertools.pairwise
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:
Add itertools.pairwise
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.