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.