[glib: 1/2] ci: Add some documentation to the style check CI test

[Emmanuele Bassi <ebassi src gnome org>]

commit 65541f1ad60fd8a89a64d288dd9c304588985468
Author: Philip Withnall <withnall endlessm com>
Date:   Thu Jan 16 13:48:33 2020 +0000

    ci: Add some documentation to the style check CI test
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 .gitlab-ci/run-style-check-diff.sh | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
---
diff --git a/.gitlab-ci/run-style-check-diff.sh b/.gitlab-ci/run-style-check-diff.sh
index 4ed6284b6..097b43d60 100755
--- a/.gitlab-ci/run-style-check-diff.sh
+++ b/.gitlab-ci/run-style-check-diff.sh
@@ -14,3 +14,18 @@ git fetch upstream
 # a merge request pipeline; fall back to `${CI_DEFAULT_BRANCH}` otherwise.
 newest_common_ancestor_sha=$(diff --old-line-format='' --new-line-format='' <(git rev-list --first-parent 
upstream/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-${CI_DEFAULT_BRANCH}}) <(git rev-list --first-parent HEAD) | 
head -1)
 git diff -U0 --no-color "${newest_common_ancestor_sha}" | ./clang-format-diff.py -binary "clang-format-7" -p1
+
+# The style check is not infallible. The clang-format configuration cannot
+# perfectly describe GLib’s coding style: in particular, it cannot align
+# function arguments. The documented coding style for GLib takes priority over
+# clang-format suggestions. Hopefully we can eventually improve clang-format to
+# be configurable enough for our coding style. That’s why this CI check is OK
+# to fail: the idea is that people can look through the output and ignore it if
+# it’s wrong. (That situation can also happen if someone touches pre-existing
+# badly formatted code and it doesn’t make sense to tidy up the wider coding
+# style with the changes they’re making.)
+echo ""
+echo "Note that clang-format output is advisory and cannot always match the GLib coding style, documented at"
+echo "   https://gitlab.gnome.org/GNOME/gtk/blob/master/docs/CODING-STYLE";
+echo "Warnings from this tool can be ignored in favour of the documented coding style,"
+echo "or in favour of matching the style of existing surrounding code."