Add: Migration Guides

Author: nuskey8

README.md

@@ -107,6 +107,10 @@ or open Packages/manifest.json and add the following to the dependencies block.
 }
 ```
 
+### Migration Guides
+
+Magic Tween is an actively developed library, and there is a possibility of breaking changes with each version. For information on migrating from previous versions, please refer to the [Migration Guides](migration.md).
+
 ## Basic Usage
 
 By introducing Magic Tween, numerous extension methods for creating tweens on traditional Unity components are added. Below is an example of animating the position of a Transform using these extension methods:

README_JA.md

@@ -110,7 +110,7 @@ https://github.com/AnnulusGames/MagicTween.git?path=/MagicTween/Assets/MagicTwee
 
 ### 移行ガイド
 
-Magic Tweenは現在開発中のライブラリであり、バージョン毎に破壊的変更が行われる可能性があります。過去バージョンからの移行に関しては[]()を参照してください。
+Magic Tweenは現在開発中のライブラリであり、バージョン毎に破壊的変更が行われる可能性があります。過去バージョンからの移行に関しては[移行ガイド](migration_ja.md)を参照してください。
 
 ## 基本の使い方
 

migration.md

@@ -0,0 +1,90 @@
+# Migration Guides
+
+Magic Tween is an actively developed library, and there may be breaking changes associated with version updates. Here, we provide migration guides for transitioning to different versions.
+
+## v0.1 to v0.2
+
+### Overview
+
+In the transition from v0.1 to v0.2, the design of ECS tweens has been completely revamped. This means that you'll need to make some changes to your code when using Magic Tween with ECS.
+
+### Changes related to Tween.Entity
+
+Starting from v0.2, `Tween.Entity.To()` and `Tween.Entity.FromTo()` require the specification of the component type as a type argument:
+
+```cs
+Entity entity;
+float endValue;
+float duration;
+
+// v0.1
+Tween.Entity.To<ExampleTranslator>(entity, endValue, duration);
+
+// v0.2
+Tween.Entity.To<ExampleComponent, ExampleTranslator>(entity, endValue, duration);
+```
+
+### Renaming of Translator Structs for LocalTransform Support
+
+In line with the above change, we've reduced the verbosity by renaming Translator structs that support LocalTransform. In v0.2, we've removed the "LocalTransform" prefix from their names:
+
+```cs
+Entity entity;
+float3 endValue;
+float duration;
+
+// v0.1
+Tween.Entity.To<LocalTransformPositionTranslator>(entity, endValue, duration);
+
+// v0.2
+Tween.Entity.To<LocalTransform, PositionTranslator>(entity, endValue, duration);
+```
+
+## Changes related to Custom Translators
+
+We have removed the `TargetEntity` property from `ITweenTranslator`. Starting from v0.2, tracking the target entity is handled by dedicated components.
+
+```cs
+// v0.1
+public struct ExampleTranslator : ITweenTranslator<float, ExampleComponent>
+{
+    // TargetEntity is required for entity tracking
+    public Entity TargetEntity { get; set; }
+
+    public void Apply(ref ExampleComponent component, in float value)
+    {
+        component.value = value;
+    }
+
+    public float GetValue(ref ExampleComponent component)
+    {
+        return component.value;
+    }
+}
+
+// v0.2
+public struct ExampleTranslator : ITweenTranslator<float, ExampleComponent>
+{
+    // TargetEntity is no longer required
+
+    public void Apply(ref ExampleComponent component, in float value)
+    {
+        component.value = value;
+    }
+
+    public float GetValue(ref ExampleComponent component)
+    {
+        return component.value;
+    }
+}
+```
+
+Additionally, `TweenTranslationSystemBase` now has type arguments for specifying TweenOptions and TweenPlugins. Starting from v0.2, you must specify both of these when creating a system:
+
+```csharp
+// v0.1
+public partial class ExampleTweenTranslationSystem : TweenTranslationSystemBase<float, ExampleComponent, ExampleTranslator> { }
+
+// v0.2
+public partial class ExampleTweenTranslationSystem : TweenTranslationSystemBase<float, NoOptions, FloatTweenPlugins, ExampleComponent, ExampleTranslator> { }
+```

migration_ja.md

@@ -0,0 +1,90 @@
+# Migration Guides
+
+Magic Tweenは現在も開発中のライブラリであり、バージョンの移行に伴った破壊的変更が行われる可能性があります。ここでは、バージョンのアップデートに伴う移行のガイドを提供します。
+
+## v0.1 to v0.2
+
+### 概要
+
+v0.1からv0.2では、ECSに関するTweenの設計を一新しました。これにより、ECSでMagic Tweenを用いる際のコードにいくつか変更を加える必要が生じます。
+
+### Tween.Entityに関する変更
+
+`Tween.Entity.To()`および`Tween.Entity.FromTo()`はv0.2よりComponentの型引数の指定が必要になりました。
+
+```cs
+Entity entity;
+float endValue;
+float duration;
+
+// v0.1
+Tween.Entity.To<ExampleTranslator>(entity, endValue, duration);
+
+// v0.2
+Tween.Entity.To<ExampleComponent, ExampleTranslator>(entity, endValue, duration);
+```
+
+### LocalTransformに対応したTranslatorの構造体の名前を変更
+
+上記の変更に伴い、記述量を削減するためLocalTransformに対応したTranslatorの名前を変更しました。v0.2では接頭辞のLocalTransformを削除した名前に変更されています。
+
+```cs
+Entity entity;
+float3 endValue;
+float duration;
+
+// v0.1
+Tween.Entity.To<LocalTransformPositionTranslator>(entity, endValue, duration);
+
+// v0.2
+Tween.Entity.To<LocalTransform, PositionTranslator>(entity, endValue, duration);
+```
+
+## カスタムTranslatorに関する変更
+
+`ITweenTranslator`から`TargetEntity`のプロパティを削除しました。v0.2からは対象のEntityの追跡は専用のComponentによって行われます。
+
+```cs
+// v0.1
+public struct ExampleTranslator : ITweenTranslator<float, ExampleComponent>
+{
+    // Entityの追跡にTargetEntityが必要
+    public Entity TargetEntity { get; set; }
+
+    public void Apply(ref ExampleComponent component, in float value)
+    {
+        component.value = value;
+    }
+
+    public float GetValue(ref ExampleComponent component)
+    {
+        return component.value;
+    }
+}
+
+// v0.2
+public struct ExampleTranslator : ITweenTranslator<float, ExampleComponent>
+{
+    // TargetEntityが不要に
+
+    public void Apply(ref ExampleComponent component, in float value)
+    {
+        component.value = value;
+    }
+
+    public float GetValue(ref ExampleComponent component)
+    {
+        return component.value;
+    }
+}
+```
+
+また、`TweenTranslationSystemBase`にTweenOptionsとTweenPluginを指定する型引数が追加されました。v0.2からはこれら二つを指定してSystemを作成する必要があります。
+
+```cs
+// v0.1
+public partial class ExampleTweenTranslationSystem : TweenTranslationSystemBase<float, ExampleComponent, ExampleTranslator> { }
+
+// v0.2
+public partial class ExampleTweenTranslationSystem : TweenTranslationSystemBase<float, NoOptions, FloatTweenPlugins, ExampleComponent, ExampleTranslator> { }
+```