Add script to install post-commit hook, mention in devguide

docs/source/devguide/styleguide.rst

@@ -12,18 +12,21 @@ adding new code in OpenMC.
 C++
 ---
 
-.. important:: To ensure consistent styling with little effort, this project
-    uses `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_. The
-    repository contains a ``.clang-format`` file that can be used to
-    automatically apply the style rules that are described below. The easiest
-    way to use clang-format is through a plugin/extension for your editor/IDE
-    that automatically runs clang-format using the ``.clang-format`` file
-    whenever a file is saved.
+.. _styleguide_formatting:
 
-Indentation
------------
+Automatic Formatting
+--------------------
 
-Use two spaces per indentation level.
+To ensure consistent styling with little effort, this project uses `clang-format
+<https://clang.llvm.org/docs/ClangFormat.html>`_. The repository contains a
+``.clang-format`` file that can be used to automatically apply a consistent
+format. The easiest way to use clang-format is to run
+``tools/dev/install-commit-hooks.sh`` to install a post-commit hook that gets
+executed each time a commit is made. In addition, you may want to configure your
+editor/IDE to automatically runs clang-format using the ``.clang-format`` file
+whenever a file is saved. For example, `Visual Studio Code
+<https://code.visualstudio.com/docs/cpp/cpp-ide#_code-formatting>`_ includes
+support for running clang-format.
 
 Miscellaneous
 -------------
@@ -123,94 +126,6 @@ Variables declared constexpr or const that have static storage duration (exist
 for the duration of the program) should be upper-case with underscores,
 e.g., ``SQRT_PI``.
 
-Use C++-style declarator layout (see `NL.18
-<http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#nl18-use-c-style-declarator-layout>`_):
-pointer and reference operators in declarations should be placed adject to the
-base type rather than the variable name. Avoid declaring multiple names in a
-single declaration to avoid confusion:
-
-.. code-block:: C++
-
-   T* p; // good
-   T& p; // good
-   T *p; // bad
-   T* p, q; // misleading
-
-Curly braces
-------------
-
-For a class declaration, the opening brace should be on the same line that
-lists the name of the class.
-
-.. code-block:: C++
-
-    class Matrix {
-      ...
-    };
-
-For a function definition, the opening and closing braces should each be on
-their own lines.  This helps distinguish function code from the argument list.
-If the entire function fits on one or two lines, then the braces can be on the
-same line. e.g.:
-
-.. code-block:: C++
-
-    return_type function(type1 arg1, type2 arg2)
-    {
-      content();
-    }
-
-    return_type
-    function_with_many_args(type1 arg1, type2 arg2, type3 arg3,
-                            type4 arg4)
-    {
-      content();
-    }
-
-    int return_one() {return 1;}
-
-    int return_one()
-    {return 1;}
-
-For a conditional, the opening brace should be on the same line as the end of
-the conditional statement. If there is a following ``else if`` or ``else``
-statement, the closing brace should be on the same line as that following
-statement. Otherwise, the closing brace should be on its own line. A one-line
-conditional can have the closing brace on the same line or it can omit the
-braces entirely e.g.:
-
-.. code-block:: C++
-
-    if (condition) {
-      content();
-    }
-
-    if (condition1) {
-      content();
-    } else if (condition 2) {
-      more_content();
-    } else {
-      further_content();
-    }
-
-    if (condition) {content()};
-
-    if (condition) content();
-
-For loops similarly have an opening brace on the same line as the statement and
-a closing brace on its own line. One-line loops may have the closing brace on
-the same line or omit the braces entirely.
-
-.. code-block:: C++
-
-    for (int i = 0; i < 5; i++) {
-      content();
-    }
-
-    for (int i = 0; i < 5; i++) {content();}
-
-    for (int i = 0; i < 5; i++) content();
-
 Documentation
 -------------
 
@@ -226,7 +141,7 @@ Style for Python code should follow PEP8_.
 
 Docstrings for functions and methods should follow numpydoc_ style.
 
-Python code should work with Python 3.4+.
+Python code should work with Python 3.6+.
 
 Use of third-party Python packages should be limited to numpy_, scipy_,
 matplotlib_, pandas_, and h5py_. Use of other third-party packages must be

docs/source/devguide/workflow.rst

@@ -67,6 +67,11 @@ features and bug fixes. The general steps for contributing are as follows:
        cd openmc
        git checkout -b newbranch develop
 
+3. Run ``tools/dev/install-commit-hooks.sh`` to install a post-commit hook that
+   runs clang-format on C++ files to apply :ref:`automatic code formatting
+   <styleguide_formatting>`. In addition, you may want to configure your text
+   editor to automatically run clang-format when saving C++ files.
+
 3. Make your changes on the new branch that you intend to have included in
    *develop*. If you have made other changes that should not be merged back,
    ensure that those changes are made on a different branch.

tools/dev/COPYRIGHT.celeritas

@@ -0,0 +1,14 @@
+Note: this copyright applies to the following files:
+  - install-commit-hooks.sh
+  - post-commit.git-clang-format
+which originated from https://github.com/celeritas-project/celeritas
+
+Intellectual Property Notice
+----------------------------
+
+Celeritas is licensed under the Apache License, Version 2.0 (LICENSE-APACHE
+or http://www.apache.org/licenses/LICENSE-2.0) or the MIT license,
+(LICENSE-MIT or http://opensource.org/licenses/MIT), at your option.
+
+Copyrights and patents in the Celeritas project are retained by contributors.
+No copyright assignment is required to contribute to Celeritas.

tools/dev/install-commit-hooks.sh

@@ -0,0 +1,32 @@
+#!/bin/sh -e
+
+if ! hash git-clang-format ; then
+  printf "\e[31mgit-clang-format is not installed.\e[0m
+Install clang-format and update your paths.
+"
+  exit 1
+fi
+
+GIT_WORK_TREE="$(git rev-parse --show-toplevel)"
+POSTCOMMIT=${GIT_WORK_TREE}/.git/hooks/post-commit
+
+# Ensure a post-commit hook exists (Git LFS might have created one).
+if [ ! -f "${POSTCOMMIT}" ]; then
+  printf "\e[33mCreating post-commit hook at ${POSTCOMMIT}.\e[0m\n"
+  echo "#!/bin/sh" > "${POSTCOMMIT}"
+  chmod a+x "${POSTCOMMIT}"
+fi
+
+printf "\e[2;37mSetting clang format options in git config\e[0m\n"
+git config clangFormat.extension "cc,hh,h,cpp,hpp"
+git config clangFormat.style "file"
+
+if ! grep 'git-clang-format' ${POSTCOMMIT} >/dev/null ; then
+  printf "\e[33mAppending git-clang-format call to ${POSTCOMMIT}\e[0m\n"
+  cat >> "${POSTCOMMIT}" << 'EOF'
+GCF="$(git rev-parse --show-toplevel)/tools/dev/post-commit.git-clang-format"
+test -x "${GCF}" && "${GCF}" "$@"
+EOF
+fi
+
+printf "\e[0;32mPre-commit hook successfully installed for ${GIT_WORK_TREE}\e[0m\n"

tools/dev/post-commit.git-clang-format

@@ -0,0 +1,38 @@
+#!/bin/sh -e
+
+if [ -n "${SKIP_GCF}" ]; then
+  # Running inside of another git-clang-format hook
+  exit 0
+fi
+
+if ! command -v git-clang-format >/dev/null 2>&1 ; then
+  printf "\e[1;33mgit-clang-format is not installed!\e[0m
+  Install clang to enable auto-formatting.
+" >&2
+  exit 0
+fi
+
+if ! git diff-files --quiet ; then
+  printf "\e[1;33mWill not git-clang-format: repository is dirty\e[0m. \e[33m \
+Stage (with 'git add') or stash (with 'git stash') all files before committing \
+to apply formatting.\e[0m
+" >&2
+  exit 0
+fi
+
+printf "\e[2;37;40mRunning git-clang-format...\e[0m" >&2
+CLANG_FORMAT_RESULT="$(git-clang-format HEAD^)"
+
+if git diff-files --quiet ; then
+  printf "\r\e[2;32mAll code changes were properly formatted\e[0m\n" >&2
+else
+  BAD_COMMIT=$(git rev-parse --short HEAD)
+  printf "\r\e[0;33mCode formatting changes were required:\e[0m\n" >&2
+  printf "${CLANG_FORMAT_RESULT}\n" >&2
+  git add -u :/
+  SKIP_GCF=1 git commit --amend -C HEAD >/dev/null
+  GOOD_COMMIT=$(git rev-parse --short HEAD)
+  printf "\e[2;37mTo view formatting changes:
+    git diff ${BAD_COMMIT} ${GOOD_COMMIT}\e[0m
+" >&2
+fi