From e3ea432528dc5bfcdff89c1b6afeaa6d423fd4ee Mon Sep 17 00:00:00 2001 From: Karthik Nayak Date: Tue, 23 Jul 2024 10:21:06 +0200 Subject: [PATCH 1/6] clang-format: indent preprocessor directives after hash We do not have a rule around the indentation of preprocessor directives. This was also discussed on the list [1], noting how there is often inconsistency in the styling. While there was discussion, there was no conclusion around what is the preferred style here. One style being indenting after the hash: #if FOO # if BAR # include # endif #endif The other being before the hash: #if FOO #if BAR #include #endif #endif Let's pick the former and add 'IndentPPDirectives: AfterHash' value to our '.clang-format'. There is no clear reason to pick one over the other, but it would definitely be nicer to be consistent. [1]: https://lore.kernel.org/r/xmqqwmmm1bw6.fsf@gitster.g Signed-off-by: Karthik Nayak Signed-off-by: Junio C Hamano --- .clang-format | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.clang-format b/.clang-format index 3ed4fac753..5e128519bf 100644 --- a/.clang-format +++ b/.clang-format @@ -96,6 +96,12 @@ BreakStringLiterals: false # Switch statement body is always indented one level more than case labels. IndentCaseLabels: false +# Indents directives before the hash. +# #if FOO +# # include +# #endif +IndentPPDirectives: AfterHash + # Don't indent a function definition or declaration if it is wrapped after the # type IndentWrappedFunctionNames: false From 5e7eee46a3a57f13a1bd080fef777a0e5aed4cb9 Mon Sep 17 00:00:00 2001 From: Karthik Nayak Date: Tue, 23 Jul 2024 10:21:07 +0200 Subject: [PATCH 2/6] clang-format: avoid spacing around bitfield colon The spacing around colons is currently not standardized and as such we have the following practices in our code base: - Spacing around the colon `int bf : 1`: 146 instances - No spacing around the colon `int bf:1`: 148 instances - Spacing before the colon `int bf :1`: 6 instances - Spacing after the colon `int bf: 1`: 12 instances Let's formalize this by picking the most followed pattern and add the corresponding style to '.clang-format'. Signed-off-by: Karthik Nayak Signed-off-by: Junio C Hamano --- .clang-format | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.clang-format b/.clang-format index 5e128519bf..803b274dd5 100644 --- a/.clang-format +++ b/.clang-format @@ -72,6 +72,10 @@ AlwaysBreakAfterReturnType: None BinPackArguments: true BinPackParameters: true +# Add no space around the bit field +# unsigned bf:2; +BitFieldColonSpacing: None + # Attach braces to surrounding context except break before braces on function # definitions. # void foo() From 1993918b9fe13cde1a2eaaba07cb6d0c96134373 Mon Sep 17 00:00:00 2001 From: Karthik Nayak Date: Tue, 23 Jul 2024 10:21:08 +0200 Subject: [PATCH 3/6] clang-format: formalize some of the spacing rules There are some spacing rules that we follow in the project and it makes sense to formalize them: * Ensure there is no space inserted after the logical not '!' operator. * Ensure there is no space before the case statement's colon. * Ensure there is no space before the first bracket '[' of an array. * Ensure there is no space in empty blocks. Signed-off-by: Karthik Nayak Signed-off-by: Junio C Hamano --- .clang-format | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.clang-format b/.clang-format index 803b274dd5..3c8018a1dd 100644 --- a/.clang-format +++ b/.clang-format @@ -118,11 +118,18 @@ PointerAlignment: Right # x = (int32)y; not x = (int32) y; SpaceAfterCStyleCast: false +# No space is inserted after the logical not operator +SpaceAfterLogicalNot: false + # Insert spaces before and after assignment operators # int a = 5; not int a=5; # a += 42; a+=42; SpaceBeforeAssignmentOperators: true +# Spaces will be removed before case colon. +# case 1: break; not case 1 : break; +SpaceBeforeCaseColon: false + # Put a space before opening parentheses only after control statement keywords. # void f() { # if (true) { @@ -134,6 +141,14 @@ SpaceBeforeParens: ControlStatements # Don't insert spaces inside empty '()' SpaceInEmptyParentheses: false +# No space before first '[' in arrays +# int a[5][5]; not int a [5][5]; +SpaceBeforeSquareBrackets: false + +# No space will be inserted into {} +# while (true) {} not while (true) { } +SpaceInEmptyBlock: false + # The number of spaces before trailing line comments (// - comments). # This does not affect trailing block comments (/* - comments). SpacesBeforeTrailingComments: 1 From bce7e52d4e70a8d8d824596654bac85545bf9d07 Mon Sep 17 00:00:00 2001 From: Karthik Nayak Date: Tue, 23 Jul 2024 10:21:09 +0200 Subject: [PATCH 4/6] ci: run style check on GitHub and GitLab We don't run style checks on our CI, even though we have a '.clang-format' setup in the repository. Let's add one, the job will validate only against the new commits added and will only run on merge requests. Since we're introducing it for the first time, let's allow this job to fail, so we can validate if this is useful and eventually enforce it. For GitHub, we allow the job to pass by adding 'continue-on-error: true' to the workflow. This means the job would show as passed, even if the style check failed. To know the status of the job, users have to manually check the logs. For GitLab, we allow the job to pass by adding 'allow_failure: true', to the job. Unlike GitHub, here the job will show as failed with a yellow warning symbol, but the pipeline would still show as passed. Also for GitLab, we use the 'CI_MERGE_REQUEST_TARGET_BRANCH_SHA' variable by default to obtain the base SHA of the merged pipeline (which is only available for merged pipelines [1]). Otherwise we use the 'CI_MERGE_REQUEST_DIFF_BASE_SHA' variable. [1]: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html#predefined-variables-for-merge-request-pipelines Helped-by: Junio C Hamano Signed-off-by: Karthik Nayak Signed-off-by: Junio C Hamano --- .github/workflows/check-style.yml | 34 +++++++++++++++++++++++++++++++ .gitlab-ci.yml | 18 ++++++++++++++++ ci/install-dependencies.sh | 4 ++++ ci/run-style-check.sh | 8 ++++++++ 4 files changed, 64 insertions(+) create mode 100644 .github/workflows/check-style.yml create mode 100755 ci/run-style-check.sh diff --git a/.github/workflows/check-style.yml b/.github/workflows/check-style.yml new file mode 100644 index 0000000000..c052a5df23 --- /dev/null +++ b/.github/workflows/check-style.yml @@ -0,0 +1,34 @@ +name: check-style + +# Get the repository with all commits to ensure that we can analyze +# all of the commits contributed via the Pull Request. + +on: + pull_request: + types: [opened, synchronize] + +# Avoid unnecessary builds. Unlike the main CI jobs, these are not +# ci-configurable (but could be). +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + check-style: + env: + CC: clang + jobname: ClangFormat + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - run: ci/install-dependencies.sh + + - name: git clang-format + continue-on-error: true + id: check_out + run: | + ./ci/run-style-check.sh \ + "${{github.event.pull_request.base.sha}}" diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 37b991e080..2886f6e182 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -123,6 +123,24 @@ check-whitespace: rules: - if: $CI_PIPELINE_SOURCE == 'merge_request_event' +check-style: + image: ubuntu:latest + allow_failure: true + variables: + CC: clang + jobname: ClangFormat + before_script: + - ./ci/install-dependencies.sh + # Since $CI_MERGE_REQUEST_TARGET_BRANCH_SHA is only defined for merged + # pipelines, we fallback to $CI_MERGE_REQUEST_DIFF_BASE_SHA, which should + # be defined in all pipelines. + script: + - | + R=${CI_MERGE_REQUEST_TARGET_BRANCH_SHA-${CI_MERGE_REQUEST_DIFF_BASE_SHA:?}} || exit + ./ci/run-style-check.sh "$R" + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' + documentation: image: ubuntu:latest variables: diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh index 6ec0f85972..fb34ced8f0 100755 --- a/ci/install-dependencies.sh +++ b/ci/install-dependencies.sh @@ -87,6 +87,10 @@ macos-*) esac case "$jobname" in +ClangFormat) + sudo apt-get -q update + sudo apt-get -q -y install clang-format + ;; StaticAnalysis) sudo apt-get -q update sudo apt-get -q -y install coccinelle libcurl4-openssl-dev libssl-dev \ diff --git a/ci/run-style-check.sh b/ci/run-style-check.sh new file mode 100755 index 0000000000..76dd37d22b --- /dev/null +++ b/ci/run-style-check.sh @@ -0,0 +1,8 @@ +#!/bin/sh +# +# Perform style check +# + +baseCommit=$1 + +git clang-format --style file --diff --extensions c,h "$baseCommit" From 30c4f7e3504f04496c0475f5c0428b2ee261dce2 Mon Sep 17 00:00:00 2001 From: Karthik Nayak Date: Tue, 23 Jul 2024 10:21:10 +0200 Subject: [PATCH 5/6] check-whitespace: detect if no base_commit is provided The 'check-whitespace' CI script exits gracefully if no base commit is provided or if an invalid revision is provided. This is not good because if a particular CI provides an incorrect base_commit, it would fail successfully. This is exactly the case with the GitLab CI. The CI is using the "$CI_MERGE_REQUEST_TARGET_BRANCH_SHA" variable to get the base commit SHA, but variable is only defined for _merged_ pipelines. So it is empty for regular pipelines [1]. This should've failed the check-whitespace job. Let's fallback to 'CI_MERGE_REQUEST_DIFF_BASE_SHA' if "CI_MERGE_REQUEST_TARGET_BRANCH_SHA" isn't available in GitLab CI, similar to the previous commit. Let's also add a check for incorrect base_commit in the 'check-whitespace.sh' script. While here, fix a small typo too. [1]: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html#predefined-variables-for-merge-request-pipelines Helped-by: Junio C Hamano Signed-off-by: Karthik Nayak Signed-off-by: Junio C Hamano --- .gitlab-ci.yml | 7 ++++++- ci/check-whitespace.sh | 10 ++++++++-- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 2886f6e182..2589098eff 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -118,8 +118,13 @@ check-whitespace: image: ubuntu:latest before_script: - ./ci/install-dependencies.sh + # Since $CI_MERGE_REQUEST_TARGET_BRANCH_SHA is only defined for merged + # pipelines, we fallback to $CI_MERGE_REQUEST_DIFF_BASE_SHA, which should + # be defined in all pipelines. script: - - ./ci/check-whitespace.sh "$CI_MERGE_REQUEST_TARGET_BRANCH_SHA" + - | + R=${CI_MERGE_REQUEST_TARGET_BRANCH_SHA-${CI_MERGE_REQUEST_DIFF_BASE_SHA:?}} || exit + ./ci/check-whitespace.sh "$R" rules: - if: $CI_PIPELINE_SOURCE == 'merge_request_event' diff --git a/ci/check-whitespace.sh b/ci/check-whitespace.sh index db399097a5..c40804394c 100755 --- a/ci/check-whitespace.sh +++ b/ci/check-whitespace.sh @@ -9,7 +9,7 @@ baseCommit=$1 outputFile=$2 url=$3 -if test "$#" -ne 1 && test "$#" -ne 3 +if test "$#" -ne 1 && test "$#" -ne 3 || test -z "$1" then echo "USAGE: $0 [ ]" exit 1 @@ -21,6 +21,12 @@ commitText= commitTextmd= goodParent= +if ! git rev-parse --quiet --verify "${baseCommit}" +then + echo "Invalid '${baseCommit}'" + exit 1 +fi + while read dash sha etc do case "${dash}" in @@ -67,7 +73,7 @@ then goodParent=${baseCommit: 0:7} fi - echo "A whitespace issue was found in onen of more of the commits." + echo "A whitespace issue was found in one or more of the commits." echo "Run the following command to resolve whitespace issues:" echo "git rebase --whitespace=fix ${goodParent}" From 1b8f30661214db117c5f7552b98e50a616c353dc Mon Sep 17 00:00:00 2001 From: Karthik Nayak Date: Tue, 23 Jul 2024 10:21:11 +0200 Subject: [PATCH 6/6] ci/style-check: add `RemoveBracesLLVM` in CI job MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For 'clang-format', setting 'RemoveBracesLLVM' to 'true', adds a check to ensure we avoid curly braces for single-statement bodies in conditional blocks. However, the option does come with two warnings [1]: This option will be renamed and expanded to support other styles. and Setting this option to true could lead to incorrect code formatting due to clang-format’s lack of complete semantic information. As such, extra care should be taken to review code changes made by this option. The latter seems to be of concern. While we want to experiment with the rule, adding it to the in-tree '.clang-format' could affect end-users. Let's only add it to the CI jobs for now. With time, we can evaluate its efficacy and decide if we want to add it to '.clang-format' or retract it entirely. We do so, by adding the existing rules in '.clang-format' and this rule to a temp file outside the working tree, which is then used by 'git clang-format'. This ensures we don't murk with files in-tree. [1]: https://clang.llvm.org/docs/ClangFormatStyleOptions.html#removebracesllvm Signed-off-by: Karthik Nayak Signed-off-by: Junio C Hamano --- ci/run-style-check.sh | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/ci/run-style-check.sh b/ci/run-style-check.sh index 76dd37d22b..6cd4b1d934 100755 --- a/ci/run-style-check.sh +++ b/ci/run-style-check.sh @@ -5,4 +5,21 @@ baseCommit=$1 -git clang-format --style file --diff --extensions c,h "$baseCommit" +# Remove optional braces of control statements (if, else, for, and while) +# according to the LLVM coding style. This avoids braces on simple +# single-statement bodies of statements but keeps braces if one side of +# if/else if/.../else cascade has multi-statement body. +# +# As this rule comes with a warning [1], we want to experiment with it +# before adding it in-tree. since the CI job for the style check is allowed +# to fail, appending the rule here allows us to validate its efficacy. +# While also ensuring that end-users are not affected directly. +# +# [1]: https://clang.llvm.org/docs/ClangFormatStyleOptions.html#removebracesllvm +{ + cat .clang-format + echo "RemoveBracesLLVM: true" +} >/tmp/clang-format-rules + +git clang-format --style=file:/tmp/clang-format-rules \ + --diff --extensions c,h "$baseCommit"