diff --git a/doc/contributing.rst b/doc/contributing.rst index 16a266c21bd849784f850e45349b1127ad9bc993..e22e06c668e536ce337d1eefd2e54001492a50e9 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -121,6 +121,45 @@ For branches which are available to others, do a proper merge: This may require some manual conflict solving and will end up in a merge commit. +-------------------------------------------------------------------------------- +|git| Hooks +-------------------------------------------------------------------------------- +|git| hooks are scripts invoked by |git| in connection to certain commands. +|project| currently provides one for :command:`commit`. It is installed by + +.. code-block:: console + + $ cp extras/pre_commit/pre-commit .git/hooks/ + $ + +Its task is applying coding standards and doing a bunch of other checks on the +files involved in a commit. Everything around the script is hosted in :file:`extras/pre_commit/`. + +If you ever have to skip the hook, + +.. code-block:: console + + $ git commit --no-verify + $ + +does the trick. **But** checks are always run on the complete file containing +changes, not only on the lines changed. This means if you opt out of an issue, +it will reappear next time that very file changes. + +For checking |python| code, the pre-commit hook employs |pylint|_, to make sure +we stay close to |pep8|_. If you feel the need to make changes to the |pylint| +call, please make sure you fully understand what the complaints are. Sometimes +|pep8| sounds overly restrictive but it may help with performance and +compatibility with |python| 3. For |project| it is also important that the code +looks similar throughout the various modules. So do not disable a check because +it just seems inconvenient or you do not understand why |pylint| is croaking at +what looks like 'working' code. But then there are also cases where |pylint| is +not smart enough to cope with valid |pep8| code. For changes with valid cause, +the configuration flushed into |pylint| may be found at +:file:`extras/pre_commit/pm3_csc/filecheck/pylintrc` and +:file:`extras/pre_commit/pm3_csc/filecheck/pylint-unittest-rc`. The latter one +is invoked on unit test code, where we may go a little bit less restrictive. + -------------------------------------------------------------------------------- Directory Structure -------------------------------------------------------------------------------- @@ -635,7 +674,10 @@ contributions to web pages using |project|. .. |fedora| replace:: Fedora .. |nameattr| replace:: :attr:`__name__` - +.. |pylint| replace:: Pylint +.. _pylint: http://www.pylint.org +.. |pep8| replace:: PEP 8 +.. _pep8: https://www.python.org/dev/peps/pep-0008/ .. LocalWords: cmake hotfix doctest linkcheck rebase BRANCHNAME rebasing py .. LocalWords: CMakeLists txt rst pymod init submodule src restructuredtext .. LocalWords: makefiles formatters Changelog codetest promod sidechains io @@ -646,4 +688,4 @@ contributions to web pages using |project|. .. LocalWords: SomethingTests testFileExistsFalse testutils RunTests DQMEAN .. LocalWords: pre API inline CMake hh ProMod Bienchen OST OPENSTRUCTURE .. LocalWords: mol alg conop QMEAN KIC eigen eigenvectors Lapack rawmodel -.. LocalWords: OpenStructure ost +.. LocalWords: OpenStructure ost pylint