Skip to content

Commit

Permalink
chore: Update readme on deprecations, migrations, and latest bevy commit
Browse files Browse the repository at this point in the history
  • Loading branch information
Bluefinger committed Oct 23, 2023
1 parent 7e7f13d commit 0fad555
Show file tree
Hide file tree
Showing 4 changed files with 26 additions and 21 deletions.
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ members = ["bevy_prng"]

[dependencies]
# bevy
bevy = { git = "https://github.com/bevyengine/bevy.git", rev = "1258ceb62cd8acb61f031dce128c2e04ee058538", version = "0.12.0-dev", default-features = false }
bevy = { git = "https://github.com/bevyengine/bevy.git", rev = "51c70bc98cd9c71d8e55a4656f22d0229a0ef06e", version = "0.12.0-dev", default-features = false }
bevy_prng = { path = "bevy_prng", version = "0.2" }

# others
Expand Down
21 changes: 21 additions & 0 deletions MIGRATIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Migration Notes

## Migrating from v0.2 to v0.3

As v0.3 is a breaking change to v0.2, the process to migrate over is fairly simple. The rand algorithm crates can no longer be used directly, but they can be swapped wholesale with `bevy_prng` instead. So the following `Cargo.toml` changes:

```diff
- rand_chacha = { version = "0.3", features = ["serde1"] }
+ bevy_prng = { version = "0.1", features = ["rand_chacha"] }
```

allows then you to swap your import like so, which should then plug straight into existing `bevy_rand` usage seamlessly:

```diff
use bevy::prelude::*;
use bevy_rand::prelude::*;
- use rand_chacha::ChaCha8Rng;
+ use bevy_prng::ChaCha8Rng;
```

This **will** change the type path and the serialization format for the PRNGs, but currently, moving between different bevy versions has this problem as well as there's currently no means to migrate serialized formats from one version to another yet. The rationale for this change is to enable stable `TypePath` that is being imposed by bevy's reflection system, so that future compiler changes won't break things unexpectedly as `std::any::type_name` has no stability guarantees. Going forward, this should resolve any stability problems `bevy_rand` might have and be able to hook into any migration tool `bevy` might offer for when scene formats change/update.
22 changes: 3 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Bevy Rand operates around a global entropy source provided as a resource, and th

If cloning creates a second instance that shares the same state as the original, forking derives a new state from the original, leaving the original 'changed' and the new instance with a randomised seed. Forking RNG instances from a global source is a way to ensure that one seed produces many deterministic states, while making it difficult to predict outputs from many sources and also ensuring no one source shares the same state either with the original or with each other.

Bevy Rand provides forking via `ForkableRng`/`ForkableAsRng`/`ForkableInnerRng` traits, allowing one to easily fork with just a simple `.fork_rng()` method call, making it straightforward to use. There's also `From` implementations, but from v0.4 onwards, these are considered deprecated and will likely be removed/changed in a future version.
Bevy Rand provides forking via `ForkableRng`/`ForkableAsRng`/`ForkableInnerRng` traits, allowing one to easily fork with just a simple `.fork_rng()` method call, making it straightforward to use. There's also `From` implementations, **but from v0.4 onwards, these are considered deprecated and will likely be removed/changed in a future version**.

## Using Bevy Rand

Expand Down Expand Up @@ -205,25 +205,9 @@ If that extra level of security is not necessary, but there is still need for ex
| v0.11 | v0.2, v0.3 |
| v0.10 | v0.1 |

## Migrating from v0.2 to v0.3
## Migrations

As v0.3 is a breaking change to v0.2, the process to migrate over is fairly simple. The rand algorithm crates can no longer be used directly, but they can be swapped wholesale with `bevy_prng` instead. So the following `Cargo.toml` changes:

```diff
- rand_chacha = { version = "0.3", features = ["serde1"] }
+ bevy_prng = { version = "0.1", features = ["rand_chacha"] }
```

allows then you to swap your import like so, which should then plug straight into existing `bevy_rand` usage seamlessly:

```diff
use bevy::prelude::*;
use bevy_rand::prelude::*;
- use rand_chacha::ChaCha8Rng;
+ use bevy_prng::ChaCha8Rng;
```

This **will** change the type path and the serialization format for the PRNGs, but currently, moving between different bevy versions has this problem as well as there's currently no means to migrate serialized formats from one version to another yet. The rationale for this change is to enable stable `TypePath` that is being imposed by bevy's reflection system, so that future compiler changes won't break things unexpectedly as `std::any::type_name` has no stability guarantees. Going forward, this should resolve any stability problems `bevy_rand` might have and be able to hook into any migration tool `bevy` might offer for when scene formats change/update.
Notes on migrating between versions can be found [here](MIGRATIONS.md).

## License

Expand Down
2 changes: 1 addition & 1 deletion bevy_prng/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ serialize = [
]

[dependencies]
bevy = { git = "https://github.com/bevyengine/bevy.git", rev = "1258ceb62cd8acb61f031dce128c2e04ee058538", version = "0.12.0-dev", default-features = false }
bevy = { git = "https://github.com/bevyengine/bevy.git", rev = "51c70bc98cd9c71d8e55a4656f22d0229a0ef06e", version = "0.12.0-dev", default-features = false }
rand_core = { version = "0.6", features = ["std"] }
serde = { version = "1.0", features = ["derive"], optional = true }
rand_chacha = { version = "0.3", optional = true }
Expand Down

0 comments on commit 0fad555

Please sign in to comment.