From 664b106f643d09675def6975fd679fb60f47d528 Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Wed, 11 Aug 2021 13:45:29 -0500 Subject: [PATCH] Add script to install post-commit hook, mention in devguide --- docs/source/devguide/styleguide.rst | 113 +++---------------------- docs/source/devguide/workflow.rst | 5 ++ tools/dev/COPYRIGHT.celeritas | 14 +++ tools/dev/install-commit-hooks.sh | 32 +++++++ tools/dev/post-commit.git-clang-format | 38 +++++++++ 5 files changed, 103 insertions(+), 99 deletions(-) create mode 100644 tools/dev/COPYRIGHT.celeritas create mode 100755 tools/dev/install-commit-hooks.sh create mode 100755 tools/dev/post-commit.git-clang-format diff --git a/docs/source/devguide/styleguide.rst b/docs/source/devguide/styleguide.rst index bfe2ac35f8..faeb37e230 100644 --- a/docs/source/devguide/styleguide.rst +++ b/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 `_. 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 +`_. 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 +`_ 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 -`_): -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 diff --git a/docs/source/devguide/workflow.rst b/docs/source/devguide/workflow.rst index 3d8d2e8273..44c0bbc5d5 100644 --- a/docs/source/devguide/workflow.rst +++ b/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 + `. 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. diff --git a/tools/dev/COPYRIGHT.celeritas b/tools/dev/COPYRIGHT.celeritas new file mode 100644 index 0000000000..39fad59ed1 --- /dev/null +++ b/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. diff --git a/tools/dev/install-commit-hooks.sh b/tools/dev/install-commit-hooks.sh new file mode 100755 index 0000000000..06f610da5a --- /dev/null +++ b/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" diff --git a/tools/dev/post-commit.git-clang-format b/tools/dev/post-commit.git-clang-format new file mode 100755 index 0000000000..01e67f3597 --- /dev/null +++ b/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