1 files changed, 118 insertions, 0 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644
index 0000000..a7e9d2a
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,118 @@
+How to Contribute
+=================
+
+CLI Helpers would love your help! We appreciate your time and always give credit.
+
+Development Setup
+-----------------
+
+Ready to contribute? Here's how to set up CLI Helpers for local development.
+
+1. `Fork the repository <https://github.com/dbcli/cli_helpers>`_ on GitHub.
+2. Clone your fork locally::
+
+    $ git clone <url-for-your-fork>
+
+3. Add the official repository (``upstream``) as a remote repository::
+
+    $ git remote add upstream git@github.com:dbcli/cli_helpers.git
+
+4. Set up a `virtual environment <http://docs.python-guide.org/en/latest/dev/virtualenvs>`_
+   for development::
+
+    $ cd cli_helpers
+    $ pip install virtualenv
+    $ virtualenv cli_helpers_dev
+
+   We've just created a virtual environment called ``cli_helpers_dev``
+   that we'll use to install all the dependencies and tools we need to work on CLI Helpers.
+   Whenever you want to work on CLI Helpers, you need to activate the virtual environment::
+
+    $ source cli_helpers_dev/bin/activate
+
+   When you're done working, you can deactivate the virtual environment::
+
+    $ deactivate
+
+5. From within the virtual environment, install the dependencies and development tools::
+
+    $ pip install -r requirements-dev.txt
+    $ pip install --editable .
+
+6. Create a branch for your bugfix or feature based off the ``master`` branch::
+
+    $ git checkout -b <name-of-bugfix-or-feature> master
+
+7. While you work on your bugfix or feature, be sure to pull the latest changes from ``upstream``.
+   This ensures that your local codebase is up-to-date::
+
+    $ git pull upstream master
+
+8. When your work is ready for the CLI Helpers team to review it,
+   make sure to add an entry to CHANGELOG file, and add your name to the AUTHORS file.
+   Then, push your branch to your fork::
+
+    $ git push origin <name-of-bugfix-or-feature>
+
+9. `Create a pull request <https://help.github.com/articles/creating-a-pull-request-from-a-fork/>`_
+   on GitHub.
+
+
+Running the Tests
+-----------------
+
+While you work on CLI Helpers, it's important to run the tests to make sure your code
+hasn't broken any existing functionality. To run the tests, just type in::
+
+    $ pytest
+
+CLI Helpers supports Python 3.6+. You can test against multiple versions of
+Python by running::
+
+    $ tox
+
+You can also measure CLI Helper's test coverage by running::
+
+    $ pytest --cov-report= --cov=cli_helpers
+    $ coverage report
+
+
+Coding Style
+------------
+
+When you submit a PR, the changeset is checked for pep8 compliance using
+`black <https://github.com/psf/black>`_. If you see a build failing because
+of these checks, install ``black`` and apply style fixes:
+
+::
+
+    $ pip install black
+    $ black .
+
+Then commit and push the fixes.
+
+To enforce ``black`` applied on every commit, we also suggest installing ``pre-commit`` and
+using the ``pre-commit`` hooks available in this repo:
+
+::
+
+    $ pip install pre-commit
+    $ pre-commit install
+
+Git blame
+---------
+
+Use ``git blame my_file.py --ignore-revs-file .git-blame-ignore-revs`` to exclude irrelevant commits
+(specifically Black) from ``git blame``. For more information,
+see `here <https://github.com/psf/black#migrating-your-code-style-without-ruining-git-blame>`_.
+
+Documentation
+-------------
+
+If your work in CLI Helpers requires a documentation change or addition, you can
+build the documentation by running::
+
+    $ make -C docs clean html
+    $ open docs/build/html/index.html
+
+That will build the documentation and open it in your web browser.