From 91f6c202d9046f827b7b77289377a6f3b5f078f0 Mon Sep 17 00:00:00 2001
From: Correl Roush <correl@gmail.com>
Date: Fri, 4 Dec 2020 22:46:40 -0500
Subject: [PATCH] Add contribution documentation to the README

---
 README.rst | 81 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 74 insertions(+), 7 deletions(-)

diff --git a/README.rst b/README.rst
index abcc5a4..df8e905 100644
--- a/README.rst
+++ b/README.rst
@@ -16,14 +16,11 @@ Provides integration between the `Tornado`_ web framework and `Openapi-core`_
 library for validating request and response objects against an `OpenAPI 3`_
 specification.
 
-
-.. _Tornado: https://www.tornadoweb.org/
-.. _Openapi-core: https://github.com/p1c2u/openapi-core
-.. _OpenAPI 3: https://swagger.io/specification/
-
+Usage
+=====
 
 Adding validation to request handlers
-=====================================
+-------------------------------------
 
 .. code:: python
 
@@ -60,7 +57,7 @@ Adding validation to request handlers
                 raise
 
 Validating a response
-=====================
+---------------------
 
 .. code:: python
 
@@ -79,3 +76,73 @@ Validating a response
             response = self.fetch("/status")
             result = validator.validate(response)
             result.raise_for_errors()
+
+Contributing
+============
+
+Getting Started
+---------------
+
+This project uses `Poetry`_ to manage its dependencies. To set up a local
+development environment, just run:
+
+.. code:: sh
+
+    poetry install
+
+Formatting Code
+---------------
+
+The `Black`_ tool is used by this project to format Python code. It is included
+as a development dependency, and should be run on all committed code. To format
+code prior to committing it and submitting a PR, run:
+
+.. code:: sh
+
+    poetry run black .
+
+Running Tests
+-------------
+
+`pytest`_ is the preferred test runner for this project. It is included as a
+development dependency, and is configured to track code coverage, `Flake8`_
+style compliance, and `Black`_ code formatting. Tests can be run in your
+development environment by running:
+
+.. code:: sh
+
+    poetry run pytest
+
+Additionally, tests can be run using `tox`_, which will run the tests using
+multiple versions of both Python and Tornado to ensure broad compatibility.
+
+Configuring Hypothesis
+^^^^^^^^^^^^^^^^^^^^^^
+
+Many of the tests make use of `Hypothesis`_ to specify their expectations and
+generate a large volume of randomized test input. Because of this, the tests may
+take a long time to run on slower computers. Three profiles are defined for
+Hypothesis to use which can be selected by setting the ``HYPOTHESIS_PROFILE``
+environment variable to one of the following values:
+
+``default``
+  Runs tests using the default Hypothesis settings (100 examples per test with a
+  default completion deadline)
+
+``dev``
+  The fastest profile, meant for local development only. Uses only 10 examples
+  per test with no completion deadline.
+
+``ci``
+  The slowest profile, used for automated testing. Uses 1000 examples per test,
+  with the default completion deadline.
+
+.. _Black: https://github.com/psf/black
+.. _Flake8: https://flake8.pycqa.org/
+.. _Hypothesis: https://hypothesis.readthedocs.io/
+.. _OpenAPI 3: https://swagger.io/specification/
+.. _Openapi-core: https://github.com/p1c2u/openapi-core
+.. _Poetry: https://python-poetry.org/
+.. _Tornado: https://www.tornadoweb.org/
+.. _pytest: https://pytest.org/
+.. _tox: https://tox.readthedocs.io/