gcc/rust/CONTRIBUTING.md

   1 ## How to contribute to GCC Rust
   2
   3 #### **Did you find a bug?**
   4
   5 * **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/Rust-GCC/gccrs/issues).
   6
   7 * If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Rust-GCC/gccrs/issues/new).
   8   Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample**
   9   or an **executable test case** demonstrating the expected behavior that is not occurring.
  10
  11 #### **Do you want to submit a patch?**
  12
  13 * Open a new GitHub pull request with the patch.
  14
  15 * Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
  16
  17 * Before submitting, GCC development requires copyright assignment or the Developer's Certificate of Origin sign-off.
  18    Please see the [Contributing to GCC](https://gcc.gnu.org/contribute.html) guide or [Developer's Certificate of Origin (DCO) Sign-off](https://gcc.gnu.org/dco.html) guide.
  19
  20 * Patches sent to the [`gcc-rust` mailing list](https://gcc.gnu.org/mailman/listinfo/gcc-rust) are likewise welcome.
  21 These will be imported into a GitHub PR to follow the normal review process,
  22 and the link to the GitHub PR sent to the submitter.
  23
  24 #### **Do you intend to add a new feature or change an existing one?**
  25
  26 * Suggest your change in the [Zulip](https://gcc-rust.zulipchat.com/) and start writing code.
  27
  28 * Do not open an issue on GitHub until you have collected positive feedback about the change.
  29   GitHub issues are primarily intended for bug reports and fixes.
  30
  31 #### **Do you have questions about the source code?**
  32
  33 * Ask any question about how to use GCCRS in [Zulip](https://gcc-rust.zulipchat.com/).
  34
  35 ### **PR Policy**
  36
  37 * The PR policy: Everything has to go through a PR
  38   - An exception to this rule will be the merge commits of updating the repo against upstream GCC
  39
  40 * Reviewers/Maintainers of the project (aka people who have bors rights) should be pinged for reviews/questions.
  41
  42 * A PR can have one or several commits (split should have a technical/logical reason, ie. no fixup-ish commit)
  43
  44 * Avoid PR's with merge commit unless there's a good reason
  45
  46 * Where possible please add test cases to `gcc/testsuite/rust/` for all PRs.
  47   Some issues may not be testable via dejagnu/automation such as debug dump changes.
  48
  49 * Follow the [GCC coding style](https://gcc.gnu.org/codingconventions.html) (see `clang-format` below).
  50
  51 * PRs won't be merged until the build and tests pass.
  52
  53 * Please take the time to create good git commit messages.
  54   See the existing format of them in the git log or refer to something like: https://chris.beams.io/posts/git-commit/
  55
  56 #### Running `clang-format` locally
  57
  58 * on all files using python scripts
  59 ... corresponding to what the _Clang Format Lint_ (`.github/workflows/clang-format.yml`)
  60 is doing, with `clang-format-10` being available locally, and avoiding the Docker overhead.
  61
  62 ```shell
  63 $ wget 'https://github.com/DoozyX/clang-format-lint-action/raw/v0.11/run-clang-format.py'
  64 $ cp contrib/clang-format .clang-format
  65 $ python3 run-clang-format.py --clang-format-executable clang-format-10 --recursive --extensions h,cc gcc/rust/
  66 ```
  67
  68 * on a given patch using python scripts
  69 See the [clang-format documentation](https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting) :
  70
  71     $ git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1
  72
  73 * using `git` interface
  74
  75 At least on Debian and its derivative, each `clang-format` packages also comes
  76 with `git-clang-format` command that can be used easily. It applies on staged
  77 changes, and any modification can be seen as unstaged changes:
  78
  79 ```diff
  80 $ git diff --cached
  81 diff --git a/gcc/rust/rust-abi.h b/gcc/rust/rust-abi.h
  82 index bd3043295ce..9559374ce60 100644
  83 --- a/gcc/rust/rust-abi.h
  84 +++ b/gcc/rust/rust-abi.h
  85 @@ -22,10 +22,10 @@ namespace Rust {
  86  enum ABI
  87  {
  88    UNKNOWN,
  89 -  RUST,
  90 +     RUST,
  91    INTRINSIC,
  92    C,
  93 -  CDECL,
  94 +     CDECL,
  95    STDCALL,
  96    FASTCALL,
  97  };
  98
  99 gccrs/gcc/rust on  dkm/clang_format [$!+?]
 100 ❯ git clang-format
 101 changed files:
 102     gcc/rust/rust-abi.h
 103
 104 gccrs/gcc/rust on  dkm/clang_format [$!+?]
 105 $ git diff rust-abi.h
 106 diff --git a/gcc/rust/rust-abi.h b/gcc/rust/rust-abi.h
 107 index 9559374ce60..bd3043295ce 100644
 108 --- a/gcc/rust/rust-abi.h
 109 +++ b/gcc/rust/rust-abi.h
 110 @@ -22,10 +22,10 @@ namespace Rust {
 111  enum ABI
 112  {
 113    UNKNOWN,
 114 -     RUST,
 115 +  RUST,
 116    INTRINSIC,
 117    C,
 118 -     CDECL,
 119 +  CDECL,
 120    STDCALL,
 121    FASTCALL,
 122  };
 123 ```
 124
 125 Also note that you can use a given version of `clang-format` by using `git clang-format-10` if you have
 126 installed that particular version.
 127
 128 Thanks! :heart: :heart: :heart:
 129
 130 GCCRS Team