From 3c3c0262c0d2bb937b7f4bf42f8e7becdb1baea3 Mon Sep 17 00:00:00 2001
From: Samuel Colvin <samcolvin@gmail.com>
Date: Fri, 11 Jan 2019 21:08:14 +0000
Subject: [PATCH] add contributing docs,  (#354)

* add contributing docs, fix #353

* tweaks

* tweaks
---
 .github/PULL_REQUEST_TEMPLATE.md |  1 +
 Makefile                         |  2 +-
 docs/examples/contributing.sh    | 27 +++++++++++++++++++++++++++
 docs/index.rst                   | 21 +++++++++++++++++++++
 4 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 docs/examples/contributing.sh

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index f1b4c8b..978b619 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,4 +1,5 @@
 <!-- Thank you for your contribution! -->
+<!-- See https://pydantic-docs.helpmanual.io/#contributing-to-pydantic for help on Contributing -->
 <!-- Don't worry about making lots of commits on a pull request, they'll be squashed on merge anyway -->
 
 ## Change Summary
diff --git a/Makefile b/Makefile
index 020cbb9..df128b9 100644
--- a/Makefile
+++ b/Makefile
@@ -4,7 +4,7 @@
 install:
 	pip install -U setuptools pip
 	pip install -U -r requirements.txt
-	pip install -U .
+	pip install -e .
 
 .PHONY: format
 format:
diff --git a/docs/examples/contributing.sh b/docs/examples/contributing.sh
new file mode 100644
index 0000000..e3daa81
--- /dev/null
+++ b/docs/examples/contributing.sh
@@ -0,0 +1,27 @@
+# 1. clone your fork and cd into the repo directory
+git clone git@github.com:<your username>/pydantic.git
+cd pydantic
+
+# 2. Set up a virtualenv for running tests
+virtualenv -p `which python3.7` env
+source env/bin/activate
+# (or however you prefer to setup a python environment, 3.6 will work too)
+
+# 3. Install pydantic, dependencies and test dependencies
+make install
+
+# 4. Checkout a new branch and make your changes
+git checkout -b my-new-feature-branch
+# make your changes...
+
+# 5. Fix formatting and imports
+make format
+# Pydantic uses black to enforce formatting and isort to fix imports
+# (https://github.com/ambv/black, https://github.com/timothycrosley/isort)
+
+# 6. Run tests and linting
+make
+# there are a few sub-commands in Makefile like `test`, `testcov` and `lint`
+# which you might want to use, but generally just `make` should be all you need
+
+# ... commit, push, and create your pull request
diff --git a/docs/index.rst b/docs/index.rst
index 718ee65..80280a8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -694,6 +694,27 @@ Below are the results of crude benchmarks comparing *pydantic* to other validati
 (See `the benchmarks code <https://github.com/samuelcolvin/pydantic/tree/master/benchmarks>`_
 for more details on the test case. Feel free to submit more benchmarks or improve an existing one.)
 
+Contributing to Pydantic
+------------------------
+
+We'd love you to contribute to *pydantic*, it should be extremely simple to get started and create a Pull Request.
+*pydantic* is released regularly so you should see your improvements release in a matter of days or weeks.
+
+If you're looking for something to get your teeth into, check out the
+`"help wanted" <https://github.com/samuelcolvin/pydantic/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22>`_
+label on github.
+
+To make contributing as easy and fast as possible, you'll want to run tests and linting locally. Luckily since
+*pydantic* has few dependencies, doesn't require compiling and tests don't need access to databases etc., setting
+up and running tests should be very simple.
+
+You'll need to have **python 3.6** or **3.7**, **virtualenv**, **git**, and **make** installed.
+
+.. literalinclude:: examples/contributing.sh
+  :language: bash
+
+**tl;dr**: use ``make format`` to fix formatting & ``make`` to run tests and linting.
+
 Using Pydantic
 --------------