Browse Source

Add pre-commit

This is helpful to automate code style checks at runtime. We include
documentation on how to run this as well as a general overview of style
guidelines in OSC.

Change-Id: I2dc5a0f760ce53269ae25677560b2611cc6bfd91
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
changes/30/780030/4
Stephen Finucane 6 months ago
parent
commit
87e6828678
  1. 29
      .pre-commit-config.yaml
  2. 53
      doc/source/contributor/developing.rst

29
.pre-commit-config.yaml

@ -0,0 +1,29 @@
---
default_language_version:
# force all unspecified python hooks to run python3
python: python3
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v3.4.0
hooks:
- id: trailing-whitespace
- id: mixed-line-ending
args: ['--fix', 'lf']
exclude: '.*\.(svg)$'
- id: check-byte-order-marker
- id: check-executables-have-shebangs
- id: check-merge-conflict
- id: debug-statements
- id: check-yaml
files: .*\.(yaml|yml)$
- repo: local
hooks:
- id: flake8
name: flake8
additional_dependencies:
- hacking>=2.0.0
- flake8-import-order>=0.13
language: python
entry: flake8
files: '^.*\.py$'
exclude: '^(doc|releasenotes|tools)/.*$'

53
doc/source/contributor/developing.rst

@ -6,16 +6,18 @@ Communication
-------------
IRC Channel
===========
~~~~~~~~~~~
The OpenStackClient team doesn't have regular meetings so if you have
questions or anything you want to discuss, come to our channel:
#openstack-sdks
Testing
-------
Tox prerequisites and installation
==================================
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Install the prerequisites for Tox:
@ -23,23 +25,22 @@ Install the prerequisites for Tox:
.. code-block:: bash
$ apt-get install gcc gettext python-dev libxml2-dev libxslt1-dev \
$ apt-get install gcc gettext python3-dev libxml2-dev libxslt1-dev \
zlib1g-dev
You may need to use pip install for some packages.
* On RHEL or CentOS including Fedora:
.. code-block:: bash
$ yum install gcc python-devel libxml2-devel libxslt-devel
$ yum install gcc python3-devel libxml2-devel libxslt-devel
* On openSUSE or SUSE linux Enterprise:
.. code-block:: bash
$ zypper install gcc python-devel libxml2-devel libxslt-devel
$ zypper install gcc python3-devel libxml2-devel libxslt-devel
Install python-tox:
@ -59,7 +60,7 @@ To run the full suite of tests maintained within OpenStackClient.
virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild
your virtualenv in a similar manner.
To run tests for one or more specific test environments(for example, the most
To run tests for one or more specific test environments (for example, the most
common configuration of the latest Python version and PEP-8), list the
environments with the ``-e`` option, separated by spaces:
@ -70,7 +71,7 @@ environments with the ``-e`` option, separated by spaces:
See ``tox.ini`` for the full list of available test environments.
Running functional tests
========================
~~~~~~~~~~~~~~~~~~~~~~~~
OpenStackClient also maintains a set of functional tests that are optimally
designed to be run against OpenStack's gate. Optionally, a developer may
@ -90,7 +91,7 @@ To run a specific functional test:
$ tox -e functional -- --regex functional.tests.compute.v2.test_server
Running with PDB
================
~~~~~~~~~~~~~~~~
Using PDB breakpoints with ``tox`` and ``testr`` normally does not work since
the tests fail with a `BdbQuit` exception rather than stopping at the
@ -109,8 +110,32 @@ For reference, the `debug`_ ``tox`` environment implements the instructions
.. _`debug`: https://wiki.openstack.org/wiki/Testr#Debugging_.28pdb.29_Tests
Building the Documentation
--------------------------
Coding Style
------------
OpenStackClient uses `flake8`__ along with `hacking`__, an OpenStack-specific
superset of ``flake8`` rules, to enforce coding style. This can be run manually
using ``tox``:
.. code-block:: bash
$ tox -e pep8
Alternatively, you can use the `pre-commit framework`__ to allow running of
some linters on each commit. This must be enabled locally to function:
.. code-block:: bash
$ pip install --user pre-commit
$ pre-commit install --allow-missing-config
.. __: https://flake8.pycqa.org/en/latest/
.. __: https://docs.openstack.org/hacking/latest/user/hacking.html
.. __: https://pre-commit.com/
Documentation
-------------
The documentation is generated with Sphinx using the ``tox`` command. To
create HTML docs, run the commands:
@ -121,6 +146,7 @@ create HTML docs, run the commands:
The resultant HTML will be in the ``doc/build/html`` directory.
Release Notes
-------------
@ -156,6 +182,7 @@ To run the commands and see results:
At last, look at the generated release notes files in ``releasenotes/build/html`` in your browser.
Testing new code
----------------
@ -174,7 +201,7 @@ or
$ pip install -e .
Standardize Import Format
=========================
~~~~~~~~~~~~~~~~~~~~~~~~~
More information about Import Format, see `Import Order Guide
<https://docs.openstack.org/hacking/latest/user/hacking.html#imports>`__.
@ -193,7 +220,7 @@ The import order shows below:
{{begin your code}}
Example
~~~~~~~
^^^^^^^
.. code-block:: python

Loading…
Cancel
Save