Contributing: Add docs about code style and clang-format

community/contributing/code_style_guidelines.rst

@@ -0,0 +1,137 @@
+.. _doc_code_style_guidelines:
+
+Code style guidelines
+=====================
+
+.. highlight:: shell
+
+When contributing to Godot's source code, you will be expected to follow the
+style guidelines outlined below. Some of them are checked via the Continuous
+Integration process and reviewers will ask you to fix potential issues, so
+best setup your system as outlined below to ensure all your commits follow the
+guidelines.
+
+C++ and Objective-C
+-------------------
+
+There are no written guidelines, but the code style agreed upon by the
+developers is enforced via the `clang-format <http://clang.llvm.org/docs/ClangFormat.html>`_
+code beautifier, which takes care for you of all our conventions.
+To name a few:
+
+- Indentation and alignment are both tab based (respectively one and two tabs)
+- One space around math and assignments operators as well as after commas
+- Pointer and reference operators are affixed to the variable identifier, not
+  to the type name
+
+The rules used by clang-format are outlined in the
+`.clang-format <https://github.com/godotengine/godot/blob/master/.clang-format>`_
+file of the Godot repository.
+
+As long as you ensure that your style matches the surrounding code and that you
+not introducing trailing whitespace or space-based indentation, you should be
+fine. If you plan to contribute regularly however, we strongly advise that you
+setup clang-format locally to check and automatically fix all your commits.
+
+.. warning:: Godot's code style should *not* be applied to thirdparty code,
+             i.e. that is included in Godot's source tree but was not written
+             specifically for our project. Such code usually come from
+             different upstream projects with their own style guides (or lack
+             thereof), and don't want to introduce differences that would make
+             syncing with upstream repositories harder.
+
+             Thirdparty code is usually included in the ``thirdparty/`` folder
+             and can thus easily be excluded from formatting scripts. For the
+             rare cases where a thirdparty code snippet needs to be included
+             directly within a Godot file, you can use
+             ``/* clang-format off */`` and ``/* clang-format on */`` to tell
+             clang-format to ignore a chunk of code.
+
+Using clang-format locally
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First of all, you will need to install clang-format. As of now, you need to use
+either clang-format 3.9.x or 4.x to be compatible with Godot's format. The
+upcoming 5.x branch changed the syntax for Obj-C and will error out.
+
+Installation
+^^^^^^^^^^^^
+
+Here's how to install clang-format:
+
+- Linux: It will usually be available out-of-the-box with the clang toolchain
+  packaged by your distribution.
+- macOS and Windows: You can download precompiled binaries from the
+  `LLVM website <http://llvm.org/releases/download.html>`_. You may need to add
+  the path to the binary's folder to your system's ``PATH`` environment
+  variable to be able to call ``clang-format`` out of the box.
+
+You then have different possibilities to apply clang-format to your changes:
+
+Manual usage
+^^^^^^^^^^^^
+
+You can apply clang-format manually one or more files with the following
+command:
+
+::
+
+    clang-format -i -style=file <path/to/file(s)>
+
+- ``-i`` means that the changes should be written directly to the file (by
+  default clang-format would only output the fixed version to the terminal).
+- ``-style=file`` tells clang-format to use the ``.clang-format`` file of
+  Godot's repository as a style guide. Note that the ``file`` part is the
+  actual "file" word, not a path to a file.
+- The path can point to several files, either one after the other or using
+  wildcards like in a typical Unix shell. Be careful when globbing so that
+  you don't run clang-format on compiled objects (.o and .a files) that are
+  in Godot's tree. So better use ``core/*.{cpp,h}`` than ``core/*``.
+
+Pre-commit hook
+^^^^^^^^^^^^^^^
+
+For ease of use, we provide a pre-commit hook for Git that will run
+clang-format automatically on all your commits to check them, and let you apply
+its changes in the final commit.
+
+This "hook" is a script which can be found in ``misc/hooks``, refer to that
+folder's README.md for installation instructions.
+
+If your clang-format is not in the ``PATH``, you may have to edit the
+``pre-commit-clang-format`` to point to the correct binary for it work.
+The hook was tested on Linux and macOS, but should also work in the Git Shell
+on Windows.
+
+IDE plugin
+^^^^^^^^^^
+
+Most IDEs or code editors have beautifier plugins that can be configured to run
+clang-format automatically, for example each time you save a file.
+
+Here is a non-exhaustive list of beautifier plugins for some IDEs:
+
+- Qt Creator: `Beautifier plugin <http://doc.qt.io/qtcreator/creator-beautifier.html>`_
+- Visual Studio Code: `Clang-Format <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`_
+- vim: `vim-clang-format <https://github.com/rhysd/vim-clang-format>`_
+
+(Pull requests welcome to extend this list with tested plugins.)
+
+Java
+----
+
+For Godot's Java code (mostly in ``platform/android``), there is currently no
+style guide, so for now try to stay consistent with the existing code.
+
+Once a style is decided upon, it could also be enforced via clang-format.
+
+Python
+------
+
+Godot's SCons buildsystem is written in Python 2, and various scripts included
+in the source tree are either in Python 2 or Python 3.
+
+For those, we follow the `PEP-8 style guide <https://www.python.org/dev/peps/pep-0008/>`_,
+this is however not as strongly enforced as for the C++ code. If you are so
+enclined, you can check and format your Python changes using
+`autopep8 <https://pypi.python.org/pypi/autopep8>`_.

community/contributing/index.rst

@@ -7,6 +7,7 @@ Contributing
 
    ways_to_contribute
    pr_workflow
+   code_style_guidelines
    bug_triage_guidelines
    documentation_guidelines
    updating_the_class_reference

community/contributing/ways_to_contribute.rst

@@ -85,6 +85,10 @@ use in the C++ code (indentation, brackets, etc.) or the git and PR workflow.
 .. seealso:: Technical details about the PR workflow are outlined in a
              specific section, :ref:`doc_pr_workflow`.
 
+             Details about the code style guidelines and the ``clang-format``
+             tool used to enforce them are outlined in
+             :ref:`doc_code_style_guidelines`.
+
 Testing and reporting issues
 ----------------------------