Merge #802

802: More help on running clang-format locally r=philberty a=dkm

Add note on using git-clang-format and clang-format-diff.py.

Remove the `clang-format` from the required items of PR as it's not enforced
anymore. It's now handled by regular code review.

Refs #242

Signed-off-by: Marc Poulhiès <dkm@kataplop.net>

Co-authored-by: Marc Poulhiès <dkm@kataplop.net>

1 files changed, 71 insertions, 7 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8a4ee59..c0d75d7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,17 +40,81 @@ These will be imported into a GitHub PR to follow the normal review process, and
 
 * Where possible please add test cases to `gcc/testsuite/rust/` for all PRs. Some issues may not be testable via dejagnu/automation such as debug dump changes.
 
-* PRs won't be merged until `clang-format` and the build and tests pass.
+* Follow the [GCC coding style](https://gcc.gnu.org/codingconventions.html) (see `clang-format` below).
 
-** Running `clang-format` locally
+* PRs won't be merged until the build and tests pass.
 
-... corresponding to what the _Clang Format Lint_ (`.github/workflows/clang-format.yml`) is doing, with `clang-format-10` being available locally, and avoiding the Docker overhead.
+* Please take the time to create good git commit messages. See the existing format of them in the git log or refer to something like: https://chris.beams.io/posts/git-commit/
+
+#### Running `clang-format` locally
 
-    $ wget 'https://github.com/DoozyX/clang-format-lint-action/raw/v0.11/run-clang-format.py'
-    $ cp contrib/clang-format .clang-format
-    $ python3 run-clang-format.py --clang-format-executable clang-format-10 --recursive --extensions h,cc gcc/rust/
+* on all files using python scripts
+... corresponding to what the _Clang Format Lint_ (`.github/workflows/clang-format.yml`) is doing, with `clang-format-10` being available locally, and avoiding the Docker overhead.
 
-* Please take the time to create good git commit messages see the existing format of them in the git log or refer to something like: https://chris.beams.io/posts/git-commit/
+```shell
+$ wget 'https://github.com/DoozyX/clang-format-lint-action/raw/v0.11/run-clang-format.py'
+$ cp contrib/clang-format .clang-format
+$ python3 run-clang-format.py --clang-format-executable clang-format-10 --recursive --extensions h,cc gcc/rust/
+```
+
+* on a given patch using python scripts
+See the [clang-format documentation](https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting) :
+
+    $ git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1
+
+* using `git` interface
+
+At least on Debian and its derivative, each `clang-format` packages also comes
+with `git-clang-format` command that can be used easily. It applies on staged
+changes, and any modification can be seen as unstaged changes:
+
+```diff
+$ git diff --cached
+diff --git a/gcc/rust/rust-abi.h b/gcc/rust/rust-abi.h
+index bd3043295ce..9559374ce60 100644
+--- a/gcc/rust/rust-abi.h
++++ b/gcc/rust/rust-abi.h
+@@ -22,10 +22,10 @@ namespace Rust {
+ enum ABI
+ {
+   UNKNOWN,
+-  RUST,
++     RUST,
+   INTRINSIC,
+   C,
+-  CDECL,
++     CDECL,
+   STDCALL,
+   FASTCALL,
+ };
+ 
+gccrs/gcc/rust on  dkm/clang_format [$!+?]
+❯ git clang-format
+changed files:
+    gcc/rust/rust-abi.h
+ 
+gccrs/gcc/rust on  dkm/clang_format [$!+?]
+$ git diff rust-abi.h
+diff --git a/gcc/rust/rust-abi.h b/gcc/rust/rust-abi.h
+index 9559374ce60..bd3043295ce 100644
+--- a/gcc/rust/rust-abi.h
++++ b/gcc/rust/rust-abi.h
+@@ -22,10 +22,10 @@ namespace Rust {
+ enum ABI
+ {
+   UNKNOWN,
+-     RUST,
++  RUST,
+   INTRINSIC,
+   C,
+-     CDECL,
++  CDECL,
+   STDCALL,
+   FASTCALL,
+ };
+```
+
+Also note that you can use a given version of `clang-format` by using `git clang-format-10` if you have installed that particular version.
 
 Thanks! :heart: :heart: :heart: