Skip to content

Commit 8d04394

Browse files
author
Mrln
committed
Update to main
1 parent ae387ff commit 8d04394

File tree

312 files changed

+16889
-6894
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

312 files changed

+16889
-6894
lines changed

Diff for: ‎.github/pull_request_template.md

-17
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,3 @@
11
## Description
22

33
Describe the changes you've made. Link to any issues this PR fixes or addresses.
4-
5-
## Test Plan
6-
7-
Explain the steps necessary to test your changes. If you used a playground, include the code in the details below.
8-
9-
Steps:
10-
1.
11-
12-
<details>
13-
14-
<summary>Playground</summary>
15-
16-
```rust
17-
PASTE YOUR PLAYGROUND CODE HERE
18-
```
19-
20-
</details>

Diff for: ‎.github/workflows/ci.yml

+88-31
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,110 @@
11
name: Rust
22

33
on:
4-
push:
5-
branches: ["main"]
64
pull_request:
7-
branches: ["main"]
5+
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
6+
branches:
7+
- main
88

99
env:
1010
CARGO_TERM_COLOR: always
1111

1212
jobs:
13-
build:
13+
valence-fmt-clippy:
1414
strategy:
15-
fail-fast: false
15+
fail-fast: true
1616
matrix:
17-
os: [ubuntu-latest, windows-latest, macos-11]
17+
platform: [windows-latest, macos-latest, ubuntu-latest]
18+
style: [default]
19+
rust:
20+
- stable
21+
include:
22+
- style: default
23+
flags: ""
1824

19-
runs-on: ${{ matrix.os }}
25+
runs-on: ${{ matrix.platform }}
2026

2127
steps:
2228
- uses: actions/checkout@v3
23-
- uses: dtolnay/rust-toolchain@stable
24-
with:
25-
components: clippy, rustfmt
26-
- run: cp tools/playground/src/playground.template.rs tools/playground/src/playground.rs
27-
- name: Set up cargo cache
28-
uses: actions/cache@v3
29-
continue-on-error: false
29+
30+
- name: Setup Rust toolchain and cache
31+
uses: actions-rust-lang/[email protected]
3032
with:
31-
path: |
32-
~/.cargo/bin/
33-
~/.cargo/registry/index/
34-
~/.cargo/registry/cache/
35-
~/.cargo/git/db/
36-
target/
37-
key: ${{ runner.os }}-cargo-target-${{ hashFiles('**/Cargo.toml') }}
38-
restore-keys: |
39-
${{ runner.os }}-cargo-target-${{ hashFiles('**/Cargo.toml') }}
40-
${{ runner.os }}-cargo-target
33+
toolchain: "stable"
34+
components: "clippy, rustfmt"
35+
36+
- name: "Copy playground"
37+
run: cp tools/playground/src/playground.template.rs tools/playground/src/playground.rs
38+
4139
- name: Install Dependencies (Linux)
4240
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
43-
if: matrix.os == 'ubuntu-latest'
44-
- name: Validate formatting
41+
if: matrix.platform == 'ubuntu-latest'
42+
43+
- name: cargo fmt
4544
run: cargo fmt --all -- --check
46-
- name: Validate documentation
47-
run: cargo doc --workspace --no-deps --all-features --document-private-items
48-
- name: Run clippy lints
49-
run: cargo clippy --workspace --no-deps --all-features --all-targets -- -D warnings
45+
46+
- name: Clippy
47+
run: cargo clippy --workspace ${{ matrix.flags }}--no-deps --all-features --all-targets -- -D warnings
48+
49+
valence-tests:
50+
strategy:
51+
fail-fast: true
52+
matrix:
53+
platform: [windows-latest, macos-latest, ubuntu-latest]
54+
style: [default]
55+
rust:
56+
- stable
57+
include:
58+
- style: default
59+
flags: ""
60+
61+
runs-on: ${{ matrix.platform }}
62+
63+
steps:
64+
- uses: actions/checkout@v3
65+
66+
- name: Setup Rust toolchain and cache
67+
uses: actions-rust-lang/[email protected]
68+
69+
- name: "Copy playground"
70+
run: cp tools/playground/src/playground.template.rs tools/playground/src/playground.rs
71+
72+
- name: Install Dependencies (Linux)
73+
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
74+
if: matrix.platform == 'ubuntu-latest'
75+
5076
- name: Run tests
51-
run: cargo test --workspace --all-features --all-targets
77+
run: cargo test --workspace ${{ matrix.flags }}--all-features --all-targets
78+
5279
- name: Run valence_nbt tests without preserve_order feature
5380
run: cargo test -p valence_nbt --all-targets
81+
82+
valence-docs:
83+
strategy:
84+
fail-fast: true
85+
matrix:
86+
platform: [windows-latest, macos-latest, ubuntu-latest]
87+
style: [default]
88+
rust:
89+
- stable
90+
include:
91+
- style: default
92+
flags: ""
93+
94+
runs-on: ${{ matrix.platform }}
95+
96+
steps:
97+
- uses: actions/checkout@v3
98+
99+
- name: Setup Rust toolchain and cache
100+
uses: actions-rust-lang/[email protected]
101+
102+
- name: "Copy playground"
103+
run: cp tools/playground/src/playground.template.rs tools/playground/src/playground.rs
104+
105+
- name: Install Dependencies (Linux)
106+
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
107+
if: matrix.platform == 'ubuntu-latest'
108+
109+
- name: Validate documentation
110+
run: cargo doc --workspace ${{ matrix.flags }}--no-deps --all-features --document-private-items

Diff for: ‎CONTRIBUTING.md

+136-11
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Valence has a public Discord server [here](https://discord.gg/8Fqqy9XrYb). Check it out if you have additional questions
1+
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
22
or comments.
33

44
# 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
77
unstable `rustfmt` settings are enabled in the project. To run `rustfmt` with the nightly toolchain, use
88
the `cargo +nightly fmt` command.
99

10-
# What issues can I work on?
10+
# What issues should I work on?
1111

1212
Issues
1313
labelled [good first issue](https://github.com/valence-rs/valence/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
14-
are a good place to start. This label is reserved for issues that shouldn't require too much specialized domain
14+
are a good place to start. This label is reserved for issues that are relatively uncontroversial and shouldn't require too much specialized domain
1515
knowledge to complete. New contributors are not required to start with these issues.
1616

1717
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.
4343

4444
Here are some rules you should follow for your code. Generally the goal here is to be consistent with existing code, the
4545
standard library, and the Rust ecosystem as a whole. Nonconforming code is not necessarily a blocker for accepting your
46-
contribution. It's just nice to have.
46+
contribution, but conformance is advised.
4747

4848
These guidelines are intended to complement
4949
the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/naming.html).
@@ -83,23 +83,34 @@ struct Bar {
8383

8484
## Getters and Setters
8585

86-
Getters and setters should be named like this:
86+
Getters should not start with a `get_` prefix.
87+
88+
<table>
89+
<tr>
90+
<th>Good</th>
91+
<th>Bad</th>
92+
</tr>
93+
<tr>
94+
<td>
8795

8896
```rust
8997
impl Foo {
9098
fn bar(&self) -> &Bar { ... }
9199
fn set_bar(&mut self, bar: Bar) { ... }
92100
}
93101
```
94-
95-
And **not** like this:
102+
</td>
103+
<td>
96104

97105
```rust
98106
impl Foo {
99107
fn get_bar(&self) -> &Bar { ... }
100108
fn set_bar(&mut self, bar: Bar) { ... }
101109
}
102110
```
111+
</td>
112+
</tr>
113+
</table>
103114

104115
See [`SocketAddr`](https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html) for an example of a standard library
105116
type that uses this convention.
@@ -111,10 +122,99 @@ this.
111122
If a `bar` field exists and no invariants need to be maintained by the getters and setters, it is usually better to make
112123
the `bar` field public.
113124

114-
## Naming Quantities
125+
## Bevy `Event`s
126+
127+
Types intended to be used as events in [`EventReader`] and [`EventWriter`] should end in the `Event` suffix.
128+
This is helpful for readers trying to distinguish events from other types in the program.
129+
130+
<table>
131+
<tr>
132+
<th>Good</th>
133+
<th>Bad</th>
134+
</tr>
135+
<tr>
136+
<td>
137+
138+
```rust
139+
struct CollisionEvent { ... }
140+
141+
fn handle_collisions(mut events: EventReader<CollisionEvent>) { ... }
142+
```
143+
</td>
144+
<td>
145+
146+
```rust
147+
struct Collision { ... }
148+
149+
fn handle_collisions(mut events: EventReader<Collision>) { ... }
150+
```
151+
</td>
152+
</tr>
153+
</table>
154+
155+
[`EventReader`]: https://docs.rs/bevy_ecs/latest/bevy_ecs/event/struct.EventReader.html
156+
[`EventWriter`]: https://docs.rs/bevy_ecs/latest/bevy_ecs/event/struct.EventWriter.html
157+
158+
## Specifying Dependencies
115159

116-
Quantities of something should be named `foo_count` where `foo` is the thing you're quantifying. It would be incorrect
117-
to name this variable `num_foos`.
160+
When adding a new dependency to a crate, make sure you specify the full semver version.
161+
162+
<table>
163+
<tr>
164+
<th>Good</th>
165+
<th>Bad</th>
166+
</tr>
167+
<tr>
168+
<td>
169+
170+
```toml
171+
[dependencies]
172+
serde_json = "1.0.96"
173+
```
174+
</td>
175+
<td>
176+
177+
```toml
178+
[dependencies]
179+
serde_json = "1"
180+
```
181+
</td>
182+
</tr>
183+
</table>
184+
185+
## Writing Unit Tests
186+
When writing unit tests, unwrap errors instead of returning them.
187+
Panicking displays the line and column of the error, which is useful for debugging.
188+
This information is lost when the error is returned.
189+
190+
<table>
191+
<tr>
192+
<th>Good</th>
193+
<th>Bad</th>
194+
</tr>
195+
<tr>
196+
<td>
197+
198+
```rust
199+
#[test]
200+
fn my_test() {
201+
some_fallible_func().unwrap();
202+
}
203+
```
204+
</td>
205+
<td>
206+
207+
```rust
208+
#[test]
209+
fn my_test() -> anyhow::Result<()> {
210+
some_fallible_func()?;
211+
// ...
212+
Ok(())
213+
}
214+
```
215+
</td>
216+
</tr>
217+
</table>
118218

119219
## Documentation
120220

@@ -127,4 +227,29 @@ where appropriate.
127227
Unit tests help your contributions last! They ensure that your code works as expected and that it continues to work in
128228
the future.
129229

130-
You can find examples of unit tests in the `unit_test/example.rs` module.
230+
whole-server unit tests can be found in [`crates/valence/src/tests/`](crates/valence/src/tests).
231+
232+
## Naming Quantities
233+
234+
Variables intended to hold quantities should be written with the `_count` suffix instead of the `num_` prefix.
235+
236+
<table>
237+
<tr>
238+
<th>Good</th>
239+
<th>Bad</th>
240+
</tr>
241+
<tr>
242+
<td>
243+
244+
```rust
245+
let block_count = ...;
246+
```
247+
</td>
248+
<td>
249+
250+
```rust
251+
let num_blocks = ...;
252+
```
253+
</td>
254+
</tr>
255+
</table>

0 commit comments

Comments
 (0)