102 lines
2.8 KiB
ReStructuredText
102 lines
2.8 KiB
ReStructuredText
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 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. 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, 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
|
|
------------
|
|
|
|
CLI Helpers requires code submissions to adhere to
|
|
`PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_.
|
|
It's easy to check the style of your code, just run::
|
|
|
|
$ pep8radius master
|
|
|
|
If you see any PEP 8 style issues, you can automatically fix them by running::
|
|
|
|
$ pep8radius master --in-place
|
|
|
|
Be sure to commit and push any PEP 8 fixes.
|
|
|
|
|
|
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.
|