From c8ed403b5c26a6e0b2b1417936668c5beebd336e Mon Sep 17 00:00:00 2001
From: Adrien BON <63343541+adrien-bon@users.noreply.github.com>
Date: Fri, 15 Nov 2024 18:57:59 +0000
Subject: [PATCH] doc: add migration guide from v0.4.0

---
 CHANGELOG.md                | 13 ++++++++++-
 README.md                   |  4 ++--
 book/src/SUMMARY.md         |  1 +
 book/src/migrations/v0_4.md |  7 +++---
 book/src/migrations/v0_5.md | 44 +++++++++++++++++++++++++++++++++++++
 5 files changed, 62 insertions(+), 7 deletions(-)
 create mode 100644 book/src/migrations/v0_5.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6ef2c81..082261d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,18 @@
 
 ## [unreleased]
 
+**BREAKING CHANGES**
+This version brings breaking changes.
+A [migration guide](https://adrien-bon.github.io/bevy_ecs_tiled/migrations/v0_5.html) is available to help adapt to these.
+
+### Features
+
+- Update to Bevy 0.15
+
+### Changed
+
+- Remove `map_initial_transform` and `map_initial_visibility` from `TiledMapSettings`, use required components instead
+
 ## v0.4.0
 
 **BREAKING CHANGES**
@@ -10,7 +22,6 @@ A [migration guide](https://adrien-bon.github.io/bevy_ecs_tiled/migrations/v0_4.
 
 ### Features
 
-- Update to Bevy 0.15
 - Add map loading events to give user access to Tiled internal data structure.
 - Add various settings to control where we spawn the map.
 
diff --git a/README.md b/README.md
index 3c6c8c1..89c01d3 100644
--- a/README.md
+++ b/README.md
@@ -103,8 +103,8 @@ You can browse the [examples](https://github.com/adrien-bon/bevy_ecs_tiled/tree/
 
 |bevy|bevy_ecs_tilemap|bevy_ecs_tiled|
 |---|---|---|
-|0.15|0.15|0.4|
-|0.14|0.14|0.3|
+|0.15|0.15|0.5|
+|0.14|0.14|0.3 - 0.4|
 |0.13|main@e4f3cc6|branch 0.2|
 |0.12|0.12|0.1|
 
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 16f5a05..b9234ba 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -21,6 +21,7 @@
 
 # Migration guides
 
+- [From v0.4.X to v0.5.X](migrations/v0_5.md)
 - [From v0.3.X to v0.4.X](migrations/v0_4.md)
 
 # Miscellaneous
diff --git a/book/src/migrations/v0_4.md b/book/src/migrations/v0_4.md
index 4f24d0c..8a68849 100644
--- a/book/src/migrations/v0_4.md
+++ b/book/src/migrations/v0_4.md
@@ -2,9 +2,7 @@
 
 ## Overview
 
-Version 0.4 was initially motivated by an update to the way we handle user properties.
-
-It ended as a major overhaul of the plugin to provide a better API which gives more control to the user and update the crate for Bevy v0.15.
+Version 0.4 was initially motivated by an update to the way we handle user properties but ended as a major overhaul of the plugin to provide a better API and to give more control to the user.
 
 ## Plugin instanciation
 
@@ -33,7 +31,8 @@ The plugin configuration is described in the [API reference](https://docs.rs/bev
 The plugin entry point, ie. the `TiledMapBundle` bundle is gone.
 It was cumbersome and did not allow for a proper separation of concerns (for instance, for physics).
 
-Also, the `Handle<TiledMap>` type is not a Bevy component anymore, since Bevy `Handle<T>` now cannot derive the `Component` trait.
+Also, the `Handle<TiledMap>` type is not a Bevy component anymore.
+It was done in order to anticipate expected changes in Bevy where `Handle<T>` won't be able to derive the `Component` trait anymore.
 
 Anyway, the new way to spawn a map is now easier: you just have to spawn a `TiledMapHandle` referencing your .TMX file asset:
 
diff --git a/book/src/migrations/v0_5.md b/book/src/migrations/v0_5.md
new file mode 100644
index 0000000..a8ad580
--- /dev/null
+++ b/book/src/migrations/v0_5.md
@@ -0,0 +1,44 @@
+# From v0.4.X to v0.5.X
+
+## Overview
+
+Version 0.5 updates the crate for Bevy v0.15.
+
+It also takes advantages of the new `required_component` feature to simplify the crate API.
+
+## Bevy v0.15 update
+
+[Bevy official migration guide](https://bevyengine.org/learn/migration-guides/0-14-to-0-15/)
+
+## Misc changes
+
+### `TiledMapSettings` update
+
+`map_initial_transform` and `map_initial_visibility` have been removed from `TiledMapSettings`.
+
+If you want to tweak your map positioning or visibility, you should instead directly insert corresponding `Transform` or `Visibility` components on it.
+
+Before:
+
+```rust,no_run
+    let map_handle: Handle<TiledMap> = asset_server.load("map.tmx");
+    commands.spawn((
+        TiledMapHandle(map_handle),
+        TiledMapSettings {
+            map_initial_transform: Transform::from_xyz(150., 100., 0.),
+            map_initial_visibility: Visibility::Hidden,
+            ..Default::default()
+        },
+    ));
+```
+
+After:
+
+```rust,no_run
+    let map_handle: Handle<TiledMap> = asset_server.load("map.tmx");
+    commands.spawn((
+        TiledMapHandle(map_handle),
+        Transform::from_xyz(150., 100., 0.),
+        Visibility::Hidden,
+    ));
+```