summaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--CONTRIBUTING.rst118
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.