Update ReadMe and Contributing files

Bromeon · Bromeon · commit 6c05d02fa9b0 · 2022-02-12T21:35:25.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,70 +1,62 @@
-# Contributing to godot's rust bindings.
+# Contributing to the godot-rust library
 
 The godot-rust bindings developers welcome contribution from everyone. Here are the guidelines if you are thinking of helping us:
 
-## Contributions
 
-Contributions should be made in the form of GitHub pull requests (PRs). Each pull request will be reviewed by a core contributor (someone with permission to land patches) and either landed in the main tree or given feedback for changes that would be required.
+## Submitting a PR
 
-When opening a PR, our continuous integration (CI) pipeline will automatically perform a few basic checks (formatting, lints, unit tests). Please make sure those checks pass, adjusting your code if necessary.
+Contributions should be made in the form of GitHub pull requests (PRs). Each pull request will be reviewed by the godot-rust team or other contributors.
 
-Should you wish to work on an issue, please claim it first by commenting on the GitHub issue that you want to work on it. This is to prevent duplicated efforts from contributors on the same issue.
 
-## Getting started
+### Picking a task
 
-Have a look at the [issues](https://github.com/godot-rust/godot-rust/issues) to find good tasks to start with.
+Have a look at the [issue tracker] to find good tasks to start with. Should you wish to work on an issue, please claim it first by commenting in it. This is to prevent duplicated efforts from contributors on the same issue.
 
-## Pull Request Checklist
+We especially appreciate input on the issues labeled [`help wanted`]. The label [`good first issue`] encompasses issues which do not require a deep prior knowledge of the godot-rust intricacies and could be picked up by a newcomer.
 
-- Branch from the master branch and, if needed, rebase to the current master branch before submitting your pull request. If it doesn't merge cleanly with master you may be asked to rebase your changes.
+You can also open a pull request directly without an associated issue. Note however that discussing the issue with other developers beforehand increases the chances of a PR being accepted, and may save time on both your and the reviewer's end. Such discussions can also happen in our Discord server.
 
-- Use one commit per logical change. Often, PRs only consist of a single commit. If you change unrelated parts of the code, split it into separate commits.
 
-- If your patch is not getting reviewed or you need a specific person to review it, you can @-reply a reviewer asking for a review in the pull request or a comment.
+### Git workflow
 
-- Whenever applicable, add tests relevant to the fixed bug or new feature.
+* Branch from the `master` branch and, if needed, rebase to the current `master` branch before submitting your pull request. If it doesn't merge cleanly, you may be asked to rebase your changes.
 
-- Use `cargo fmt` to format your code.
+* Use one commit per logical change. Often, PRs only consist of a single commit. If you change unrelated parts of the code, split it into separate commits.
 
-## Testing
+* If your patch is not getting reviewed or you need a specific person to review it, you can @-reply a reviewer asking for a review in the pull request or a comment.
 
-Everywhere: run `cargo test --workspace` from the root of the repository.
 
-On GNU/Linux operating systems:
+### Writing tests
 
-```
-cd test
-cargo build
-cp ../target/debug/libgdnative_test.so ./project/lib/
-godot --path ./project
-```
+Whenever applicable, add tests relevant to the fixed bug or new feature.
 
-The `godot` command in the above snippet is your local installation of godot and may vary depending on how it was installed.
+Some types and functions can only be used if the engine is running. In order to test them, use the `godot_test!` macro, and explicitly invoke the test functions in [test/src/lib.rs](test/src/lib.rs). Don't hesitate to see how existing code does this.
 
-### Automating tests
+  
+### Local and CI checks
 
-If you are on a bash-compatible system, you can use the `pre-commit.sh` to automatically run your tests every time you try to commit code.  You can install it with:
+The repository root contains a script `check.sh`. If you invoke it without arguments, it will run a list of basic checks locally. This tool also allows you to quickly build RustDoc documentation of changed APIs. Please run `./check.sh --help` for more information about its usage.
 
-```sh
-$ ln -s ../../hooks/pre-commit.sh .git/hooks/pre-commit
-$ chmod +x .git/hooks/pre-commit
-```
+If you use Windows, you might consider using a Unix shell interpreter (e.g. one shipped with Git-for-Windows, or WSL2, or similar).
 
-If you don't need to run tests on your commit, you can simply run `git commit --no-verify` to skip the pre-commit script.  The pre-commit script handles a few edge cases as well, by stashing all of your changes before running tests, just in case your unstashed changes mask errors in the bare commit.  This is especially useful if you've stopped working on something to make a quick patch.
+Additionally, when opening a PR, our continuous integration (CI) pipeline will automatically perform a few checks (formatting, lints, unit tests). Please make sure all of them pass, adjusting your code where necessary.
 
-## Writing tests
-
-Some types can only be used if the engine is running, in order to test them, use the `godot_test!` macro (see examples in [variant.rs](gdnative/src/variant.rs)), and explicitly invoke the test functions in [test/src/lib.rs](test/src/lib.rs).
 
 ## Communication
 
-Primary communication between developers of the project happens on the `godot-rust` Discord server. [Invite link here](https://discord.gg/FNudpBD).
+Primary communication between developers of the project happens on the `godot-rust` Discord server. [Invite link here][godot-rust-discord].
 
-For questions about using `godot-rust` the `#gdnative` channel on the [Godot Engine community Discord server](https://godotengine.org/community) can be used.
-On IRC the `#godotengine-gdnative` channel on freenode can be used for questions as well.
+For questions about Godot, check out the options on the [Godot community page][godot-community]. For example, their Discord server hosts a `#gdnative-dev` channel for questions regarding GDNative interface. The contributor chat is helpful in case of discussions about Godot's own design and implementation.
 
-If you are only interested in occasional announcements and showcases, follow [@GodotRust on Twitter](https://twitter.com/GodotRust). For questions and design discussions, please use Discord.
+If you are only interested in occasional announcements and showcases, follow [@GodotRust on Twitter][godot-rust-twitter]. For questions and design discussions, please use Discord.
 
 ## License
 
 Any contribution submitted for inclusion in the work by you shall be licensed under the [MIT license](LICENSE.md), without any additional terms or conditions.
+
+[issue tracker]: https://github.com/godot-rust/godot-rust/issues
+[`help wanted`]: https://github.com/godot-rust/godot-rust/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
+[`good first issue`]: https://github.com/godot-rust/godot-rust/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+[godot-community]: https://godotengine.org/community
+[godot-rust-discord]: https://discord.gg/FNudpBD
+[godot-rust-twitter]: https://twitter.com/GodotRust
diff --git a/README.md b/README.md
@@ -2,11 +2,11 @@
 
 <a href="https://godot-rust.github.io/"><img align="right" width="200" height="200" src="assets/godot-ferris.svg"></a>
 
-[![Docs Status](https://docs.rs/gdnative/badge.svg)](https://docs.rs/gdnative)
-
-
-**[Website](https://godot-rust.github.io)** |
-**[User Guide](https://godot-rust.github.io/book)** | **[Stable Docs](https://docs.rs/gdnative)** | **[Latest Docs](https://godot-rust.github.io/docs)**
+[<img alt="crates.io" src="https://img.shields.io/crates/v/gdnative?logo=rust&color=A6854D" />](https://crates.io/crates/gdnative)
+[<img alt="stable docs" src="https://img.shields.io/badge/docs-released-4D8AA6?&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" />](https://docs.rs/gdnative)
+[<img alt="master docs" src="https://img.shields.io/badge/docs-master-4D8AA6?&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" />](https://godot-rust.github.io/docs)
+[<img alt="book" src="https://img.shields.io/badge/user_guide-book-3e6ccf?&logo=read-the-docs&logoColor=white" />](https://godot-rust.github.io/book)
+[<img alt="website" src="https://img.shields.io/badge/website-3e6ccf?&color=gray" />](https://godot-rust.github.io)
 
 **godot-rust** is a Rust library that implements native bindings for the [Godot game engine](http://godotengine.org/). This allows you to develop games or other applications in Godot, while benefiting from Rust's strengths, such as its type system, scalability and performance.
 
@@ -25,23 +25,10 @@ For versions 3.2 and 3.3, some extra steps are needed, see _Custom builds_ below
 
 The bindings do _**not**_ support in-development Godot 4 versions at the moment. Support is planned as the native extensions become more stable.
 
-## Requirements
-
-The generator makes use of `bindgen`, which depends on Clang. Instructions for installing `bindgen`'s dependencies for popular OSes can be found [in their documentation](https://rust-lang.github.io/rust-bindgen/requirements.html).
-
-`bindgen` may complain about a missing `llvm-config` binary, but it is not actually required to build the `gdnative` crate. If you see a warning about `llvm-config` and a failed build, it's likely that you're having a different problem!
-
-### 'Header not found' errors
-
-When building the library, `bindgen` may produce errors that look like this:
-
-```
-godot-rust\gdnative-sys/godot_headers\gdnative/string.h:39:10: fatal error: 'wchar.h' file not found
-```
 
-This means that `bindgen` was unable to find the C system headers for your platform. If you can locate the headers manually, you may try setting the `C_INCLUDE_PATH` environment variable so `libclang` could find them. If on Windows, you may try building from the Visual Studio "developer console", which should setup the appropriate variables for you.
+## Getting started
 
-## Usage
+Detailed setup is explained in [the _Getting Started_ section of the book](https://godot-rust.github.io/book/getting-started.html). In case of problems, consider also reading the [FAQ](https://godot-rust.github.io/book/faq/configuration.html).
 
 ### Latest `master` version + Godot 3.4
 
@@ -78,15 +65,11 @@ Async support is a work-in-progress, with a low-level API available in the `gdna
 
 ## Example
 
-The most general use-case of the bindings will be to interact with Godot using the generated wrapper
-classes, as well as providing custom functionality by exposing Rust types as *NativeScript*s.
+A typical use case is to expose your own _Native Class_, a Rust API that can be invoked from the Godot engine. The resulting native script can be attached to the scene tree, just like GDScript (`.gd` files). 
 
-NativeScript is an extension for GDNative that allows a dynamic library to register "script classes"
-to Godot.
+This happens via dynamic libraries and the _GDNative interface_, which will be loaded from Godot. The necessary wiring is done behind the scenes by godot-rust. A simple "Hello world" application could look like this:
 
-As is tradition, a simple "Hello World" should serve as an introduction. For a full tutorial, check out ["Getting Started" from the user guide](https://godot-rust.github.io/book/getting-started.html)!
-
-```rust
+```rs
 use gdnative::prelude::*;
 
 #[derive(NativeClass)]
@@ -112,14 +95,14 @@ fn init(handle: InitHandle) {
 godot_init!(init);
 ```
 
-### Further examples
 
+### Further examples
 
-> ### **IMPORTANT NOTE**
+> **Important note:**
 >
-> Before launching the examples in the godot editor, you must first run `cargo build` and wait for the build operations to finish successfully.
+> Before launching the examples in the Godot editor, you must first run `cargo build` and wait for the build operations to finish successfully.
 >
->At startup, the Godot editor tries to load all resources used by the project, including the native binary. If it isn't present, the editor skips properties or signals associated with the missing NativeScripts in the scene. This will cause the scene tree to be non-functional for any sample that relies on properties or signals configured in the editor.
+>At startup, the Godot editor tries to load all resources used by the project, including the native library. If the latter isn't present, the editor will skip properties or signals associated with the missing native scripts in the scene. This will cause the scene tree to be non-functional for any sample that relies on properties or signals configured in the editor.
 
 The [/examples](https://github.com/godot-rust/godot-rust/tree/master/examples) directory contains several ready to use examples, complete with Godot projects and setup for easy compilation from Cargo:
 
@@ -133,31 +116,17 @@ The [/examples](https://github.com/godot-rust/godot-rust/tree/master/examples) d
 - [**rpc**](https://github.com/godot-rust/godot-rust/tree/master/examples/rpc) - Simple peer-to-peer networking.
 - [**native-plugin**](https://github.com/godot-rust/godot-rust/tree/master/examples/native-plugin) - Create custom node plugins.
 
-## Third-party resources
-
-See also (work-in-progress): [Third-party projects](https://godot-rust.github.io/book/projects.html) in the book.
-
-### Tools and integrations
 
-- [godot-egui](https://github.com/setzer22/godot-egui) (setzer22, jacobsky) - combine the [egui](https://github.com/emilk/egui) library with Godot 
-- [ftw](https://github.com/macalimlim/ftw) (macalimlim) - manage your godot-rust projects from the command line
+### Third-party projects
 
-### Open-source games
-
-- [Action RPG](https://github.com/MacKarp/Rust_Action_RPG_Tutorial) (MacKarp) - this [Godot tutorial](https://www.youtube.com/playlist?list=PL9FzW-m48fn2SlrW0KoLT4n5egNdX-W9a) ported to Rust.
-- [Air Combat](https://github.com/paytonrules/AirCombat) (paytonrules) - this [Godot tutorial](https://devga.me/tutorials/godot2d/) ported to Rust.
-- [Simple single-player Blackjack](https://github.com/paytonrules/Blackjack) (paytonrules)
-- [Pong](https://github.com/you-win/godot-pong-rust) (you-win)
-
-### Tutorials
-
-- Step by step guide - [Up and running with Rust and Godot: A basic setup](https://hagsteel.com/posts/godot-rust/)
+To see a list of games and integrations developed on top of godot-rust, have a look at our list of [third-party projects](https://godot-rust.github.io/book/projects.html) in the book.
 
 
 ## Contributing
 
 See the [contribution guidelines](CONTRIBUTING.md).
 
+
 ## License
 
-Any contribution intentionally submitted for inclusion in the work by you shall be licensed under the [MIT license](LICENSE.md), without any additional terms or conditions.
+Any contribution submitted for inclusion in the work by you shall be licensed under the [MIT license](LICENSE.md), without any additional terms or conditions.
