new file mode 100644
@@ -0,0 +1,130 @@
+## How to contribute to GCC Rust
+
+#### **Did you find a bug?**
+
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/Rust-GCC/gccrs/issues).
+
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Rust-GCC/gccrs/issues/new).
+ Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample**
+ or an **executable test case** demonstrating the expected behavior that is not occurring.
+
+#### **Do you want to submit a patch?**
+
+* Open a new GitHub pull request with the patch.
+
+* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
+
+* Before submitting, GCC development requires copyright assignment or the Developer's Certificate of Origin sign-off.
+ 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.
+
+* Patches sent to the [`gcc-rust` mailing list](https://gcc.gnu.org/mailman/listinfo/gcc-rust) are likewise welcome.
+These will be imported into a GitHub PR to follow the normal review process,
+and the link to the GitHub PR sent to the submitter.
+
+#### **Do you intend to add a new feature or change an existing one?**
+
+* Suggest your change in the [Zulip](https://gcc-rust.zulipchat.com/) and start writing code.
+
+* Do not open an issue on GitHub until you have collected positive feedback about the change.
+ GitHub issues are primarily intended for bug reports and fixes.
+
+#### **Do you have questions about the source code?**
+
+* Ask any question about how to use GCCRS in [Zulip](https://gcc-rust.zulipchat.com/).
+
+### **PR Policy**
+
+* The PR policy: Everything has to go through a PR
+ - An exception to this rule will be the merge commits of updating the repo against upstream GCC
+
+* Reviewers/Maintainers of the project (aka people who have bors rights) should be pinged for reviews/questions.
+
+* A PR can have one or several commits (split should have a technical/logical reason, ie. no fixup-ish commit)
+
+* Avoid PR's with merge commit unless there's a good reason
+
+* 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.
+
+* Follow the [GCC coding style](https://gcc.gnu.org/codingconventions.html) (see `clang-format` below).
+
+* PRs won't be merged until the build and tests pass.
+
+* 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
+
+* 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.
+
+```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:
+
+GCCRS Team
new file mode 100644
@@ -0,0 +1,264 @@
+
+[](https://github.com/Rust-GCC/gccrs/actions/workflows/bootstrap.yml)
+[](https://github.com/Rust-GCC/gccrs/actions/workflows/docker.yml)
+
+[](https://gcc-rust.zulipchat.com/)
+[](https://app.bors.tech/repositories/32890)
+# GCC Rust
+
+
+Please note, the compiler is in a very early stage and not usable yet for compiling real Rust programs.
+
+gccrs is a full alternative implementation of the Rust language ontop of GCC with the goal
+to become fully upstream with the GNU toolchain.
+
+The origin of this project was a community effort several years ago where Rust was still at version 0.9;
+the language was subject to so much change that it became difficult for a community effort to play catch up.
+Now that the language is stable, it is an excellent time to create alternative compilers. The developers of
+the project are keen “Rustaceans” with a desire to give back to the Rust community and to learn what GCC is capable
+of when it comes to a modern language.
+
+## Build Farm Status
+
+- [Debian i386](https://builder.sourceware.org/buildbot/#/builders/gccrust-debian-i386) [](https://builder.sourceware.org/buildbot/#/builders/gccrust-debian-i386)
+- [Debian ppc64](https://builder.sourceware.org/buildbot/#/builders/gccrust-debian-ppc64) [](https://builder.sourceware.org/buildbot/#/builders/gccrust-debian-ppc64)
+- [Debian testing-x86_64](https://builder.sourceware.org/buildbot/#/builders/146) [](https://builder.sourceware.org/buildbot/#/builders/146)
+- [Fedora arm64](https://builder.sourceware.org/buildbot/#/builders/179) [](https://builder.sourceware.org/buildbot/#/builders/179)
+- [Fedora ppc64le](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-ppc64le) [](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-ppc64le)
+- [Fedora s390x](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-s390x) [](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-s390x)
+- [Fedora X86_64](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-x86_64) [](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-x86_64)
+- [OpenSUSE Leap X86_64](https://builder.sourceware.org/buildbot/#/builders/104) [](https://builder.sourceware.org/buildbot/#/builders/104)
+- [OpenSUSE tw X86_64](https://builder.sourceware.org/buildbot/#/builders/103) [](https://builder.sourceware.org/buildbot/#/builders/103)
+- [Rawhide X86_64](https://builder.sourceware.org/buildbot/#/builders/132) [](https://builder.sourceware.org/buildbot/#/builders/132)
+
+## FAQ
+
+Please find the answers to frequently asked questions over on: https://github.com/Rust-GCC/gccrs/wiki/Frequently-Asked-Questions
+
+## Development Environment
+
+### Building
+
+Fetch dependencies for Ubuntu:
+
+```bash
+$ apt install build-essential libgmp3-dev libmpfr-dev libmpc-dev flex bison autogen gcc-multilib dejagnu
+```
+
+Clone the repository
+
+```bash
+$ git clone https://github.com/Rust-GCC/gccrs
+```
+
+#### Linux
+
+It is important to remember that GNU toolchain projects are designed to be built outside of their source directory
+which is why a build directory is created.
+
+```bash
+$ mkdir gccrs-build
+$ cd gccrs-build
+$ ../gccrs/configure --prefix=$HOME/gccrs-install --disable-bootstrap --enable-multilib --enable-languages=rust
+$ make
+```
+
+#### MacOS
+
+The path of header dir and sysroot should be specified when you configure the project.
+```bash
+$ mkdir mac-build
+$ cd mac-build
+$ ../gccrs/configure --prefix=$HOME/gccrs-install --disable-bootstrap --enable-multilib --enable-languages=rust --with-native-system-header-dir=/usr/include --with-sysroot=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk
+$ make
+
+```
+
+#### Running GCC Rust
+
+Running the compiler itself without make install we can simply invoke the compiler proper:
+
+```bash
+$ ./gcc/rust1 test.rs -frust-debug -frust-dump-parse -Warray-bounds -dumpbase test.rs -mtune=generic -march=x86-64 -O0 -version -fdump-tree-gimple -o test.s -L/lib/x86_64-linux-gnu -L/lib/../lib64 -L/usr/lib/x86_64-linux-gnu -L/usr/lib/../lib64
+```
+
+To invoke the compiler driver (gccrs) we need to:
+
+```bash
+$ make install
+```
+
+Then invoke the compiler from the installation directory:
+
+```bash
+$ $HOME/gccrs-install/gccrs -g -O2 -c test.rs -o test.o
+$ $HOME/gccrs-install/gccrs -o test test.o
+```
+
+You can also setup your shell to automatically find the installed compiler. For example for `bash`,
+add the following in your `$HOME/.bashrc`:
+
+```bash
+export PATH=$HOME/gccrs-install/bin:$PATH
+
+```
+
+## Testsuite
+
+Invoke the full testsuite from the build directory (`gccrs-build` in the previous commands):
+
+```bash
+$ make check-rust
+```
+
+Invoke a subset of the testsuite. For example, to only run tests that are currently known/expected to fail:
+
+```bash
+$ make check-rust RUNTESTFLAGS="xfail.exp"
+```
+There are the following sets of tests:
+- `compile.exp` : compilation tests
+- `execute.exp` : execution tests
+- `xfail.exp` : tests that are currently known/expected to fail
+
+Invoke only a specific test :
+
+```bash
+$ make check-rust RUNTESTFLAGS="--all compile.exp=continue1.rs"
+```
+
+Logs (with corresponding commands) can be found in : `gccrs-build/gcc/testsuite/rust/rust.log`.
+
+See [GCC Testing documentation](https://gcc.gnu.org/install/test.html) for more details.
+
+Test cases are located within [`gcc/testsuite/rust/`](gcc/testsuite/rust/).
+Please contribute your specific
+test cases referencing any issues on Github.
+
+## Debugging
+
+### Enabling internal checks
+
+GCC has several internal checks that can be enabled during configuration. In the case of `gccrs`,
+you can enable the following:
+```bash
+$ ../gccrs/configure --prefix=$HOME/gccrs-install --disable-bootstrap --enable-multilib --enable-languages=rust --enable-checking=gimple,tree,types
+```
+
+### GDB
+You can directly invoke `gdb` on the `rust1` compiler process (you can find the
+exact command adding `--verbose` to your `gccrs` invocation):
+```bash
+$ gccrs test.rs -O0 -S -o arithmetic_expressions1.s --verbose
+...
+ /some/path/../../rust1 test.rs -quiet -dumpbase arithmetic_expressions1.rs -dumpbase-ext .rs
+ -mtune=generic -march=x86-64 -O0 -w -version -fdiagnostics-color=never -fno-diagnostics-show-caret -fno-diagnostics-show-line-numbers -fdiagnostics-urls=never -fdiagnostics-path-format=separate-events -o test.s -L/lib/x86_64-linux-gnu -L/lib/../lib64 -L/usr/lib/x86_64-linux-gnu
+...
+$ gdb --args /some/path/../../rust1 test.rs -quiet -dumpbase arithmetic_expressions1.rs -dumpbase-ext .rs
+ -mtune=generic -march=x86-64 -O0 -w -version -fdiagnostics-color=never -fno-diagnostics-show-caret -fno-diagnostics-show-line-numbers -fdiagnostics-urls=never -fdiagnostics-path-format=separate-events -o test.s -L/lib/x86_64-linux-gnu -L/lib/../lib64 -L/usr/lib/x86_64-linux-gnu
+```
+
+Or simply add the `-wrapper gdb,--args` option.
+This will call each subcommand in `gdb` and you simply have to break/debug in `rust1`:
+```bash
+$ gccrs test.rs -O0 -S -o arithmetic_expressions1.s -wrapper gdb,--args
+```
+
+## Docker image
+
+There is a docker image hosted over on:
+
+https://hub.docker.com/repository/docker/philberty/gccrs
+
+```bash
+$ docker pull philberty/gccrs
+```
+
+Or you can build your own image:
+
+```bash
+$ docker build . -t gccrs-dev
+```
+If you want to build an object file:
+
+```bash
+$ docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp \
+ gccrs-dev:latest gccrs -g -O2 -c \
+ gcc/testsuite/rust/compile/torture/type_infer1.rs -o type_infer1.o
+```
+
+If you want to build an executable file:
+```bash
+$ docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp \
+ gccrs-dev:latest gccrs -g -O2 \
+ gcc/testsuite/rust/compile/torture/type_infer1.rs -o type_infer1
+```
+
+To emit assembly :
+```bash
+$ docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp \
+ gccrs-dev:latest gccrs -g -O2 \
+ gcc/testsuite/rust/compile/torture/type_infer1.rs -S -o type_infer1.s
+```
+
+To emit Rust front end debug output, you may add options like `-frust-debug`, `-frust-dump-all`.
+
+
+## Contributing
+
+If you want to contribute to GCC Rust, you can find more information in [CONTRIBUTING.md](https://github.com/Rust-GCC/gccrs/blob/master/CONTRIBUTING.md).
+
+Please be aware this project is designed to be pushed upstream to GCC when we reach some milestones,
+and this means we require copyright assignment or the Developer's Certificate of Origin sign-off.
+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.
+
+Not all contributions must be code; we would love to see new test cases or bugs and issues to be reported.
+Feel free to add any comments on open PRs
+
+
+## Continuous Integration
+
+When submitting (or updating) a [GitHub Pull Request](https://github.com/Rust-GCC/gccrs/pull/),
+several automated checks are run.
+Generally, a "green status" is necessary before merge.
+
+
+### Compiler Diagnostics
+
+That is, here, diagnostics emitted by the "initial" compiler used to build GCC/Rust.
+
+If building a native toolchain,
+GCC by default does a 3-stage bootstrap build (<https://gcc.gnu.org/install/configure.html>).
+In addition to making sure that GCC is able to reproduce itself bit-by-bit,
+this also means that stages 2+ are built with `-Werror`
+(turning most _warning_ into _error_ diagnostics; see `--enable-werror`,
+possibly enabled by default).
+This helps to catch a good number of bugs, because it enforces that GCC compiles without compiler diagnostics;
+it's a requirement for upstream patch submission (<https://gcc.gnu.org/contribute.html#testing>).
+
+GCC generally is only expected to be "warning-clean" without `--disable-bootstrap`
+(that is, default `--enable-bootstrap` for a native build),
+and not for the initial stage where it's using the "initial" compiler -- otherwise
+we're at the mercy of whatever "initial" compiler we're using.
+Doing a `--disable-bootstrap` build is much faster, of course, so we're often doing that:
+for example, per the instructions above, or in the standard CI.
+With that, we're missing out on the aspect that _enforces that GCC compiles without compiler diagnostics_.
+
+To encounter that, the default CI has a [_check for new warnings_ step](https://github.com/Rust-GCC/gccrs/pull/1026)
+that verifies in the CI `--disable-bootstrap` build configuration that no new warnings are introduced.
+If that step fails, it usually points out a new _warning_ you've introduced erroneously, and should address.
+Occasionally it means that simply the `.github/bors_log_expected_warnings` file needs to be updated,
+for example if due to any kind of "environmental changes" (for example, CI "initial" compiler changes).
+Unless diligently reproducing the CI configuration (in particular "initial" compiler, GCC version),
+it's not really feasible to reproduce this check locally.
+If in doubt, do a local `--enable-bootstrap` build, or submit your changes, and wait for the CI system's results.
+
+
+## Community
+
+We can be found on all usual Rust channels such as Zulip, but we also have our own channels:
+
+* GCC Rust Zulip: https://gcc-rust.zulipchat.com/
+* Twitter: https://twitter.com/gcc_rust
+* GCC Mailing List: https://gcc.gnu.org/mailman/listinfo/gcc-rust
+* irc: irc.oftc.net - gccrust
new file mode 100644