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>
This commit is contained in:
Stephen Finucane
parent
8e3dde03f9
commit
87e6828678
29
.pre-commit-config.yaml
Normal file
29
.pre-commit-config.yaml
Normal file
@ -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)/.*$'
|
||||
@ -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…
Reference in New Issue
Block a user