=======================
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*.

.. _a new issue: https://github.com/maxfischer2781/asyncstdlib/issues/new

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`_.

.. _GitHub's forks: https://guides.github.com/activities/forking/
.. _how to update your fork to the upstream repository: https://medium.com/@topspinj/how-to-git-rebase-into-a-forked-repo-c9f05e821c8a

Development Environment
=======================
To set up the development environment on your computer, change to the local
repository and:

* Create the virtual environment in ``venv`` directory:

  .. code-block::

      python -m venv venv


* Activate the virtual environment, on Windows:

  .. code-block::

      venv\Scripts\activate


  or on Linux/Mac:

  .. code-block::

      . venv/bin/activate

* Install the test dependencies and documentation dependencies of
  ``asyncstdlib``:

  .. code-block::

      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`_:

  .. code-block::

      python -m flake8

* Check the code formatting with `Black`_:

  .. code-block::

      python -m black --target-version py36 --diff --check asyncstdlib unittests

  You can also automatically format the code with:

  .. code-block::

    python -m black --target-version py36 asyncstdlib unittests

* Run unit tests and measure the code coverage by:

  .. code-block::

      python -m coverage run -m pytest

  The HTML report of the coverage can be generated by:

  .. code-block::

      coverage html

  The report on coverage is stored in the ``htmlcov/`` directory.

  Make sure that your test provide a full coverage of your code.

.. _flake8: https://flake8.pycqa.org/en/latest/
.. _Black: https://github.com/psf/black

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.

.. _Sphinx: https://www.sphinx-doc.org/en/master/

To generate the documentation, change to ``docs/`` and execute, on Windows:

.. code-block::

    make.bat html

or on Linux/Mac:

.. code-block::

    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:

.. code-block::

    added itertools.pairwise

.. code-block::

    documented itertools.pairwise


.. _past tense: https://en.wikipedia.org/wiki/Past_tense

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.

.. _imperative mood: https://en.wikipedia.org/wiki/Imperative_mood

Here is an example of a title of the pull request:

.. code-block::

    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.