diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000000..d2c8f8b875 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,41 @@ +--- +default_language_version: + # force all unspecified python hooks to run python3 + python: python3 +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + - id: mixed-line-ending + args: ['--fix', 'lf'] + exclude: '.*\.(svg)$' + - id: fix-byte-order-marker + - id: check-merge-conflict + - id: debug-statements + - id: check-json + files: .*\.json$ + - id: check-yaml + files: .*\.(yaml|yml)$ + - repo: https://github.com/Lucas-C/pre-commit-hooks + rev: v1.5.4 + hooks: + - id: remove-tabs + exclude: '.*\.(svg)$' + - repo: https://opendev.org/openstack/hacking + rev: 6.1.0 + hooks: + - id: hacking + additional_dependencies: [] + exclude: '^(doc|releasenotes|tools)/.*$' + - repo: https://github.com/codespell-project/codespell + rev: v2.2.6 + hooks: + - id: codespell + - repo: https://github.com/sphinx-contrib/sphinx-lint + rev: v0.6.8 + hooks: + - id: sphinx-lint + args: [--enable=default-role] + files: ^doc/|releasenotes|api-guide + types: [rst] diff --git a/doc/source/contributor/dev-quickstart.rst b/doc/source/contributor/dev-quickstart.rst index 762f249cee..922a8981c5 100644 --- a/doc/source/contributor/dev-quickstart.rst +++ b/doc/source/contributor/dev-quickstart.rst @@ -14,8 +14,29 @@ to get yourself familiar with the general git workflow we use. This guide is primarily technical in nature; for information on how the Ironic team organizes work, please see `Ironic's contribution guide `_. -This document covers both :ref:`unit` and :ref:`integrated`. New contributors -are recommended to start with unit tests. +This document covers :ref:`githooks`, :ref:`unit`, and :ref:`integrated`. New +contributors are recommended to setup git hooks, then continue with unit tests. + +.. _githooks: + +Git hooks +--------- +Ironic uses multiple software packages to ensure code is styled as expected. A +convenient way to ensure your code complies with these rules is via the use of +`pre-commit `_. + +To configure your environment for automatic checking of code spelling and linting +before commit, install ``pre-commit``: + + pip install --user pre-commit + cd /path/to/ironic/checkout + pre-commit install --allow-missing-config + +Now, before any commit, any changed lines will be run through our ``pre-commit`` +checks. Contributors are still encouraged to run ``pep8`` and ``codespell`` +tox environments before pushing code as an extra check. + +More information about running tests in tox available in :ref:`unit`. .. _integrated: @@ -109,7 +130,6 @@ upgrade it individually, if you need to:: Running Unit Tests Locally ========================== - If you haven't already, Ironic source code should be pulled directly from git:: # from a user-writable directory, usually $HOME or $HOME/dev @@ -117,10 +137,10 @@ If you haven't already, Ironic source code should be pulled directly from git:: cd ironic -Most of the time, you will want to run unit tests and pep8 checks. This can be -done with the following command:: +Most of the time, you will want to run codespell, unit tests, and pep8 checks. +This can be done with the following command:: - tox -e pep8,py3 + tox -e codespell,pep8,py3 Ironic has multiple test environments that can be run by tox. An incomplete list of environments and what they do is below. Please reference the ``tox.ini`` @@ -133,6 +153,8 @@ file in the project you're working on for a complete, up-to-date list. - Description * - pep8 - Run style checks on code, documentation, and release notes. + * - codespell + - Check code against a list of known-misspelled words. * - py - Run unit tests with the specified python version. For example, ``py310`` will run the unit tests with python 3.10. * - unit-with-driver-libs