Contributing guidelines

.gitignore

@@ -70,6 +70,7 @@ target/
 # virtualenv
 venv/
 ENV/
+.venv/
 
 # OS X
 .DS_Store

CONTRIBUTING.rst

@@ -0,0 +1,78 @@
+Guidelines for Contributing
+===========================
+
+PyPika welcomes contributions in all forms. These may be bugs, feature requests, documentation, or examples. Please feel free to:
+
+#. Submitting an issue
+#. Opening a pull request
+#. Helping with outstanding issues and pull requests 
+
+Open an issue
+-------------
+
+If you find a bug or have a feature request, please `open an issue <https://github.com/kayak/pypika/issues>`_ on GitHub. Please just check that the issue doesn't already exist before opening a new one.
+
+Local development steps
+-----------------------
+
+Create a forked branch of the repo
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Do this once but keep it up to date
+
+#. `Fork the kayak/PyPika repo GitHub <https://github.com/kayak/pypika/fork>`_
+#. Clone forked repo and set upstream
+
+.. code-block:: bash
+
+    git clone [email protected]:<your-username>/pypika.git
+    cd pypika
+    git remote add upstream [email protected]:kayak/pypika.git
+
+Setup local development environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Setup up python virtual environment
+
+    Create and activate the environment. Here is an example using ``venv`` from the standard library:
+
+    .. code-block:: bash
+
+        python -m venv .venv
+        source .venv/bin/activate
+
+#. Install python dependencies for development
+
+    With the virtual environment activated, install the development requirements, pre-commit, and the package itself:
+
+    .. code-block:: bash
+
+        make install
+
+#. Build the docs locally
+
+    .. code-block:: bash 
+
+        make docs.build
+
+    Open the docs in your browser. For instance, on macOS:
+
+    .. code-block:: bash
+
+        open docs/_build/index.html
+
+#. Run the tests
+
+    .. code-block:: bash 
+
+        make test
+
+    These tests will also run on GitHub Actions when you open a pull request.
+
+Pull Request checklist
+----------------------
+
+- Passing tests
+- pre-commit hooks passing
+- Docstring and examples and checking for correct rendering in the docs
+

Makefile

@@ -0,0 +1,23 @@
+# You can set these variables from the command line.
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = docs
+BUILDDIR      = docs/_build
+
+
+help:            ## Show this help.
+	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
+
+install:         ## Install development dependencies
+	pip install -r requirements-dev.txt pre-commit -e . 
+	pre-commit install
+
+test:            ## Run tests
+	tox
+
+docs.build:      ## Build the documentation
+	$(SPHINXBUILD) $(SOURCEDIR) $(BUILDDIR) -b html -E
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)."
+
+docs.clean:      ## Remove the generated documentation
+	rm -rf $(BUILDDIR)

README.rst

@@ -1370,9 +1370,17 @@ This produces:
 
 .. _tutorial_end:
 
+.. _contributing_start: 
 
-.. _license_start:
+Contributing
+------------
+
+We welcome community contributions to |Brand|. Please see the `contributing guide <6_contributing.html>`_ to more info.
 
+.. _contributing_end:
+
+
+.. _license_start:
 
 License
 -------

docs/6_contributing.rst

@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst

docs/index.rst

@@ -9,6 +9,10 @@ PyPika - Python Query Builder
    :start-after: _appendix_start:
    :end-before:  _appendix_end:
 
+.. include:: ../README.rst
+   :start-after: _contributing_start:
+   :end-before:  _contributing_end:
+
 Contents
 --------
 
@@ -20,6 +24,7 @@ Contents
     3_advanced
     4_extending
     5_reference
+    6_contributing
 
 Indices and tables
 ------------------

requirements-dev.txt

@@ -2,6 +2,7 @@
 Sphinx==1.6.5
 sphinx-rtd-theme==0.2.4
 bumpversion==0.5.3
+jinja2<3.1.0
 
 # Testing
 parameterized==0.7.0