Update to main

valence-rs · Jun 11, 2023 · b69399d · b69399d
1 parent ae387ff
commit b69399d
Show file tree

Hide file tree

Showing 312 changed files with 16,889 additions and 6,894 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,20 +1,3 @@
 ## Description
 
 Describe the changes you've made. Link to any issues this PR fixes or addresses.
-
-## Test Plan
-
-Explain the steps necessary to test your changes. If you used a playground, include the code in the details below.
-
-Steps:
-1.
-
-<details>
-
-<summary>Playground</summary>
-
-```rust
-PASTE YOUR PLAYGROUND CODE HERE
-```
-
-</details>
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,53 +1,110 @@
 name: Rust
 
 on:
-  push:
-    branches: ["main"]
   pull_request:
-    branches: ["main"]
+  push: # Run CI on the main branch after every merge. This is important to fill the GitHub Actions cache in a way that pull requests can see it
+    branches:
+      - main
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  build:
+  valence-fmt-clippy:
     strategy:
-      fail-fast: false
+      fail-fast: true
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-11]
+        platform: [windows-latest, macos-latest, ubuntu-latest]
+        style: [default]
+        rust:
+          - stable
+        include:
+          - style: default
+            flags: ""
 
-    runs-on: ${{ matrix.os }}
+    runs-on: ${{ matrix.platform }}
 
     steps:
       - uses: actions/checkout@v3
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          components: clippy, rustfmt
-      - run: cp tools/playground/src/playground.template.rs tools/playground/src/playground.rs
-      - name: Set up cargo cache
-        uses: actions/cache@v3
-        continue-on-error: false
+
+      - name: Setup Rust toolchain and cache
+        uses: actions-rust-lang/[email protected]
         with:
-          path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
-          key: ${{ runner.os }}-cargo-target-${{ hashFiles('**/Cargo.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-target-${{ hashFiles('**/Cargo.toml') }}
-            ${{ runner.os }}-cargo-target
+          toolchain: "stable"
+          components: "clippy, rustfmt"
+
+      - name: "Copy playground"
+        run: cp tools/playground/src/playground.template.rs tools/playground/src/playground.rs
+
       - name: Install Dependencies (Linux)
         run: sudo apt-get update && sudo apt-get install -y libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev libclang-dev libgtk-3-dev
-        if: matrix.os == 'ubuntu-latest'
-      - name: Validate formatting
+        if: matrix.platform == 'ubuntu-latest'
+
+      - name: cargo fmt
         run: cargo fmt --all -- --check
-      - name: Validate documentation
-        run: cargo doc --workspace --no-deps --all-features --document-private-items
-      - name: Run clippy lints
-        run: cargo clippy --workspace --no-deps --all-features --all-targets -- -D warnings
+
+      - name: Clippy
+        run: cargo clippy --workspace ${{ matrix.flags }}--no-deps --all-features --all-targets -- -D warnings
+
+  valence-tests:
+    strategy:
+      fail-fast: true
+      matrix:
+        platform: [windows-latest, macos-latest, ubuntu-latest]
+        style: [default]
+        rust:
+          - stable
+        include:
+          - style: default
+            flags: ""
+
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Rust toolchain and cache
+        uses: actions-rust-lang/[email protected]
+
+      - name: "Copy playground"
+        run: cp tools/playground/src/playground.template.rs tools/playground/src/playground.rs
+
+      - name: Install Dependencies (Linux)
+        run: sudo apt-get update && sudo apt-get install -y libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev libclang-dev libgtk-3-dev
+        if: matrix.platform == 'ubuntu-latest'
+
       - name: Run tests
-        run: cargo test --workspace --all-features --all-targets
+        run: cargo test --workspace ${{ matrix.flags }}--all-features --all-targets
+
       - name: Run valence_nbt tests without preserve_order feature
         run: cargo test -p valence_nbt --all-targets
+
+  valence-docs:
+    strategy:
+      fail-fast: true
+      matrix:
+        platform: [windows-latest, macos-latest, ubuntu-latest]
+        style: [default]
+        rust:
+          - stable
+        include:
+          - style: default
+            flags: ""
+
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Rust toolchain and cache
+        uses: actions-rust-lang/[email protected]
+
+      - name: "Copy playground"
+        run: cp tools/playground/src/playground.template.rs tools/playground/src/playground.rs
+
+      - name: Install Dependencies (Linux)
+        run: sudo apt-get update && sudo apt-get install -y libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev libclang-dev libgtk-3-dev
+        if: matrix.platform == 'ubuntu-latest'
+
+      - name: Validate documentation
+        run: cargo doc --workspace ${{ matrix.flags }}--no-deps --all-features --document-private-items
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-Valence has a public Discord server [here](https://discord.gg/8Fqqy9XrYb). Check it out if you have additional questions
+Valence has a public Discord server [here](https://discord.gg/8Fqqy9XrYb) and GitHub discussions [here](https://github.com/valence-rs/valence/discussions). Check those out if you have additional questions
 or comments.
 
 # What version of Rust should I use?
@@ -7,11 +7,11 @@ To _use_ Valence, only the most recent stable version of Rust is required. Howev
 unstable `rustfmt` settings are enabled in the project. To run `rustfmt` with the nightly toolchain, use
 the `cargo +nightly fmt` command.
 
-# What issues can I work on?
+# What issues should I work on?
 
 Issues
 labelled [good first issue](https://github.com/valence-rs/valence/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-are a good place to start. This label is reserved for issues that shouldn't require too much specialized domain
+are a good place to start. This label is reserved for issues that are relatively uncontroversial and shouldn't require too much specialized domain
 knowledge to complete. New contributors are not required to start with these issues.
 
 If you plan to work on something that's not an open issue, consider making one first so that it can be discussed. This
@@ -43,7 +43,7 @@ If an error does occur, it must be fixed before the pull request can be merged.
 
 Here are some rules you should follow for your code. Generally the goal here is to be consistent with existing code, the
 standard library, and the Rust ecosystem as a whole. Nonconforming code is not necessarily a blocker for accepting your
-contribution. It's just nice to have.
+contribution, but conformance is advised.
 
 These guidelines are intended to complement
 the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/naming.html).
@@ -83,23 +83,34 @@ struct Bar {
 
 ## Getters and Setters
 
-Getters and setters should be named like this:
+Getters should not start with a `get_` prefix.
+
+<table>
+<tr>
+<th>Good</th>
+<th>Bad</th>
+</tr>
+<tr>
+<td>
 
 ```rust
 impl Foo {
     fn bar(&self) -> &Bar { ... }
     fn set_bar(&mut self, bar: Bar) { ... }
 }
 ```
-
-And **not** like this:
+</td>
+<td>
 
 ```rust
 impl Foo {
     fn get_bar(&self) -> &Bar { ... }
     fn set_bar(&mut self, bar: Bar) { ... }
 }
 ```
+</td>
+</tr>
+</table>
 
 See [`SocketAddr`](https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html) for an example of a standard library
 type that uses this convention.
@@ -111,10 +122,99 @@ this.
 If a `bar` field exists and no invariants need to be maintained by the getters and setters, it is usually better to make
 the `bar` field public.
 
-## Naming Quantities
+## Bevy `Event`s
+
+Types intended to be used as events in [`EventReader`] and [`EventWriter`] should end in the `Event` suffix.
+This is helpful for readers trying to distinguish events from other types in the program.
+
+<table>
+<tr>
+<th>Good</th>
+<th>Bad</th>
+</tr>
+<tr>
+<td>
+
+```rust
+struct CollisionEvent { ... }
+
+fn handle_collisions(mut events: EventReader<CollisionEvent>) { ... }
+```
+</td>
+<td>
+
+```rust
+struct Collision { ... }
+
+fn handle_collisions(mut events: EventReader<Collision>) { ... }
+```
+</td>
+</tr>
+</table>
+
+[`EventReader`]: https://docs.rs/bevy_ecs/latest/bevy_ecs/event/struct.EventReader.html
+[`EventWriter`]: https://docs.rs/bevy_ecs/latest/bevy_ecs/event/struct.EventWriter.html
+
+## Specifying Dependencies
 
-Quantities of something should be named `foo_count` where `foo` is the thing you're quantifying. It would be incorrect
-to name this variable `num_foos`.
+When adding a new dependency to a crate, make sure you specify the full semver version.
+
+<table>
+<tr>
+<th>Good</th>
+<th>Bad</th>
+</tr>
+<tr>
+<td>
+
+```toml
+[dependencies]
+serde_json = "1.0.96"
+```
+</td>
+<td>
+
+```toml
+[dependencies]
+serde_json = "1"
+```
+</td>
+</tr>
+</table>
+
+## Writing Unit Tests
+When writing unit tests, unwrap errors instead of returning them.
+Panicking displays the line and column of the error, which is useful for debugging.
+This information is lost when the error is returned.
+
+<table>
+<tr>
+<th>Good</th>
+<th>Bad</th>
+</tr>
+<tr>
+<td>
+
+```rust
+#[test]
+fn my_test() {
+    some_fallible_func().unwrap();
+}
+```
+</td>
+<td>
+
+```rust
+#[test]
+fn my_test() -> anyhow::Result<()> {
+    some_fallible_func()?;
+    // ...
+    Ok(())
+}
+```
+</td>
+</tr>
+</table>
 
 ## Documentation
 
@@ -127,4 +227,29 @@ where appropriate.
 Unit tests help your contributions last! They ensure that your code works as expected and that it continues to work in
 the future.
 
-You can find examples of unit tests in the `unit_test/example.rs` module.
+whole-server unit tests can be found in [`crates/valence/src/tests/`](crates/valence/src/tests).
+
+## Naming Quantities
+
+Variables intended to hold quantities should be written with the `_count` suffix instead of the `num_` prefix.
+
+<table>
+<tr>
+<th>Good</th>
+<th>Bad</th>
+</tr>
+<tr>
+<td>
+
+```rust
+let block_count = ...;
+```
+</td>
+<td>
+
+```rust
+let num_blocks = ...;
+```
+</td>
+</tr>
+</table>