Update contribution setup (#133)

* first steps towards better GH integration

* so this is what they call templates...

* shortened contrib, use RST directives only

Author: maxfischer2781

.github/CONTRIBUTING.rst

@@ -0,0 +1 @@
+../docs/source/contributing.rst

.github/ISSUE_TEMPLATE/01-bug_report.yml

@@ -0,0 +1,36 @@
+name: Bug Report
+description: Report broken or unexpected features
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: "Thanks for taking the time to help us help you!"
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: "Shortly outline the bug in your own words. A few sentences are enough."
+      placeholder: "When I do X then Y happens. But Z should happen instead!"
+    validations:
+      required: true
+  - type: textarea
+    id: mre
+    attributes:
+      label: Minimal Reproducible Example
+      description: Please create a short example code that demonstrates the bug.
+      render: python
+      value: |
+        import asyncio
+        import asyncstdlib as a
+
+        async def example():
+            # TODO: add code that triggers the bug here
+
+        asyncio.run(example())
+  - type: checkboxes
+    id: self-assign
+    attributes:
+      label: Request Assignment [Optional]
+      options:
+        - label: I already understand the cause and want to submit a bugfix.

.github/ISSUE_TEMPLATE/02-feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature Request
+description: Request new or missing features
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: "Thanks for taking the time to help us help you!"
+  - type: textarea
+    id: outline
+    attributes:
+      label: Describe the feature
+      description: "Shortly outline the feature in your own words. A few sentences are enough."
+      placeholder: "When I do X then Y should happen. It is important that X/Y can do Z!"
+    validations:
+      required: true
+  - type: checkboxes
+    id: self-assign
+    attributes:
+      label: Request Assignment [Optional]
+      options:
+        - label: I already have a plan and want to submit an implementation.

.github/PULL_REQUEST_TEMPLATE/01-pull_request.md

@@ -0,0 +1,9 @@
+<!--- AAAA Use the title to summarize the key change of this PR AAAA -->
+
+This PR changes/fixes <!--- Give a short pitch for the PR! Finishing this sentence is enough! -->. Notable changes include:
+
+<!--- Adjust, extend or shorten the below list as appropriate. This forms the summary that helps us understand your content changes. -->
+* Fixed some thing
+* Changed another thing
+
+Closes #<!---issue number -->

docs/source/contributing.rst

@@ -2,178 +2,81 @@
 Contribution Guidelines
 =======================
 
-Contributions in code to the ``asyncstdlib`` library are highly welcome!
+Contributions to ``asyncstdlib`` are highly welcome!
+The place to go is the `asyncstdlib GitHub repository`_
+where you can report bugs, request improvements or propose changes.
 
-We describe below how you can create a pull request and have it merged in.
+- For bug reports and feature requests simply `open a new issue`_
+  and fill in the appropriate template.
+- Even for content submissions it is highly recommended to make sure an issue
+  exists - this allows you to get early feedback and document the development.
+  You can use whatever tooling you like to create the content,
+  but the next sections give a rough outline on how to proceed.
 
-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*.
+.. _asyncstdlib GitHub repository: https://github.com/maxfischer2781/asyncstdlib
+.. _open a new issue: https://github.com/maxfischer2781/asyncstdlib/issues/new/choose
 
-.. _a new issue: https://github.com/maxfischer2781/asyncstdlib/issues/new
+Submitting Content
+==================
 
-Fork
-====
-We develop using `GitHub's forks`_:
+To submit concrete content suggestions you *must* use a `GitHub Fork and Pull Request`_.
+This lets you create the content at your own pace yet still receive direct feedback.
+Feel free to start with a *Draft Pull Request* to get feedback early.
 
-* 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).
+All content goes through mandatory automated and manual review.
+You can run most of the automated review yourself to get faster feedback,
+yet it is also fine to wait for the checks run on GitHub itself.
+Dependencies for automated code and documentation checking is available via
+the extras ``test`` and ``doc``, respectively.
 
-Please see the page on `GitHub's forks`_ for more detailed instruction.
+.. note::
 
-Also see this page on `how to update your fork to the upstream repository`_.
+    Ideally you develop with the repository checked out locally and a separate `Python venv`_.
+    If you have the venv active and the current working directory is the repository root,
+    simply run `python -m pip install -e '.[test,doc]'` to install all dependencies.
 
-.. _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
+.. _`GitHub Fork and Pull Request`: https://guides.github.com/activities/forking/
+.. _`Python venv`: https://docs.python.org/3/library/venv.html
 
-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::
+Testing Code
+------------
 
-    added itertools.pairwise
+Code is verified locally using the tools `flake8`, `black`, `pytest` and `mypy`.
+If you do not have your own preferences we recommend the following order:
 
-.. code-block::
+.. code:: bash
 
-    documented itertools.pairwise
+    python -m black asyncstdlib unittests
+    python -m flake8 asyncstdlib unittests
+    python -m pytest
+    python -m mypy --pretty
 
+This runs tests from simplest to most advanced and should allow you quick development.
+Note that some additional checks are run on GitHub to check test coverage and code health.
 
-.. _past tense: https://en.wikipedia.org/wiki/Past_tense
+Building Docs
+-------------
 
-Push the commit to your remote fork and create the pull request (see
-the documentation on `Github's forks`_ for more details).
+If you change the documentation, either directly or via significant edits to docstrings,
+you can build the documentation yourself to check if everything renders as expected.
+To do so, trigger a `Sphinx build`_ to generate a HTML version of the docs:
 
-Please put the title of your pull request in `imperative mood`_ and first upper
-case.
+.. code:: bash
 
-.. _imperative mood: https://en.wikipedia.org/wiki/Imperative_mood
+    sphinx-build -M html ./docs ./docs/_build
 
-Here is an example of a title of the pull request:
+On success, simply open `./docs/_build/html/index.html` in your favourite browser.
 
-.. code-block::
+.. _`Sphinx build`: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
 
-    Add itertools.pairwise
+The Review
+----------
 
-We will review your pull request as soon as possible.
-If changes are requested, please create new commits to address the review
-comments.
+Once you mark your pull request as ready for review, be prepared for one or more rounds of comments.
+These can range from general commentary, to code suggestions, to inquiries why a specific change was made.
+We strive to give actionable advice, but whenever you have trouble understanding how to proceed -
+please just reply with a comment of your own and ask how to proceed!
 
-Once the pull request is approved, we will finally squash
-the individual commits and merge it into the main branch.
+Once all comments are resolved and your pull request was approved, sit back and relax!
+We will merge your pull request in due time and include it in the next release.
+Thanks for contributing!