Migration guide for v0.2

src/SUMMARY.md

@@ -40,3 +40,5 @@
   - [Philosophy](contribute/philosophy.md)
   - [Dev tools and testing](contribute/dev-tools.md)
   - [Code and API conventions](contribute/conventions.md)
+- [Migration guides](migrate/index.md)
+  - [Migrating to v0.2](migrate/v0.2.md)

src/migrate/v0.2.md

@@ -0,0 +1,68 @@
+<!--
+  ~ Copyright (c) godot-rust; Bromeon and contributors.
+  ~ This Source Code Form is subject to the terms of the Mozilla Public
+  ~ License, v. 2.0. If a copy of the MPL was not distributed with this
+  ~ file, You can obtain one at https://mozilla.org/MPL/2.0/.
+-->
+
+# Migrating to v0.2
+
+This chapter will guide you through the changes from godot-rust version 0.1 to 0.2. See also our [November dev update][dev-november-2024]
+for a feature overview, and our [changelog][changelog] for a detailed list of modifications. Breaking changes are marked as such in the
+changelog, and you can navigate to the respective PRs to get in-depth information.
+
+
+## Godot version support
+
+With godot-rust 0.2, Godot **4.3** is supported out of the box.
+
+Godot 4.0 is no longer supported. We're the last binding to abandon it, after 1.5 years. 4.0 offers no compatibility with today's GDExtension API,
+not even among patch versions, so using it at this point is not recommended.
+
+
+## Argument passing
+
+The biggest breaking change in 0.2 is the way arguments are passed to Godot APIs. What used to be pass-by-value everywhere, has now more
+nuance, while making calling code more concise.
+
+The following table goes into different kinds of arguments and corresponding call expressions.
+
+| Argument type              | Parameter type (v0.1 ⇾ v0.2)          | v0.1 call                      | v0.2 call       |
+|----------------------------|---------------------------------------|--------------------------------|-----------------|
+| `i32` (`Copy`)             | `i32`                                 | `func(i)`                      | `func(i)`       |
+| `GString`                  | `GString` ⇾ `impl AsArg<GString>`     | `func(s)`<br>`func(s.clone())` | `func(&s)`      |
+| `&str`                     | "                                     | `func("str".into())`           | `func("str")`   |
+| `String`                   | "                                     | `func(s.into())`               | `func(&s)`      |
+| `StringName`<br>`NodePath` | "                                     | `func(s.into())`               | `func(s.arg())` |
+| `Gd<Node>`                 | `Gd<Node>` ⇾ `impl AsObjectArg<Node>` | `func(g.clone())`              | `func(&g)`      |
+| `Gd<Node2D>`               | "                                     | `func(g.clone().upcast())`     | `func(&g)`      |
+
+Most of them are straightforward, noteworthy is maybe `arg()` as a way to convert between the 3 Godot string types.
+This conversion is done explicitly, because it's much less obvious than conversion from `String`/`&str` but can have significant
+performance implications due to allocations, re-encoding and synchronization overhead. It also makes you more aware of the string
+type in use.
+
+
+## Removed APIs
+
+See also [#808]. Noteworthy changes:
+
+- Renamed crate feature `custom-godot` ⇾ `api-custom`.
+- Godot enums now use `SHOUT_CASE` enumerators. `PascalCase` aliases have been around for some time, but not anymore.
+- `GString::chars_checked()` and `GString::chars_unchecked()` have been removed. There's no more need for unsafety; use `GString::chars()` instead.
+- Several collection methods have been migrated, e.g. `Dictionary::try_get()` ⇾ `get()`, `Packed*Array::set()` ⇾ `[]`.
+- Removed ancient pre-0.1 modules `godot::engine`, `godot::log`.
+- The `#[base]` attribute is no longer allowed.
+
+
+## Miscellaneous
+
+- Some use cases now require a `Base<T>` field that wasn't previously needed, e.g. `OnReady<T>`.
+- Virtual functions that are semantically required by Godot are now also required in the `I*` interface trait in Rust.
+  That is, you must override them in your `impl` block.
+- There are new validations around `Export` and `#[class(tool)]`, which no longer accept previously compiling (but broken) code.
+
+
+[#808]: https://github.com/godot-rust/gdext/pull/808
+[changelog]: https://github.com/godot-rust/gdext/blob/master/Changelog.md#v020
+[dev-november-2024]: https://godot-rust.github.io/dev/november-2024-update