Add migration guide

packages/freezed/README.md

@@ -8,6 +8,10 @@
 
 Welcome to [Freezed], yet another code generator for data classes, tagged unions, nested classes and cloning.
 
+# Migration to 3.0.0
+
+To migrate from 2.0.0 to 3.0.0, see [changelog](CHANGELOG.md#300---2025-02-25) and our [migration guide](migration_guide.md).
+
 # Motivation
 
 Dart is awesome, but defining a "model" can be tedious. You have to:
@@ -23,12 +27,13 @@ and affect the readability of your model significantly.
 Freezed tries to fix that by implementing most of this for you, allowing you
 to focus on the definition of your model.
 
-| Before                                                                                       | After                                                                                       |
-| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Before                                                                                                  | After                                                                                       |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | ![before](https://raw.githubusercontent.com/rrousselGit/freezed/refs/heads/master/resources/before.png) | ![before](https://raw.githubusercontent.com/rrousselGit/freezed/master/resources/after.png) |
 
 # Index
 
+- [Migration to 3.0.0](#migration-to-300)
 - [Motivation](#motivation)
 - [Index](#index)
 - [How to use](#how-to-use)

packages/freezed/migration_guide.md

@@ -0,0 +1,47 @@
+## Migrate from v2 to v3
+
+### Require keyword (`sealed` / `abstract`)
+
+Classes using the factory constructor now require a keyword `sealed` / `abstract`.
+
+```diff
+@freezed
+-class Person with _$Person {
++abstract class Person with _$Person {
+  const factory Person({
+    required String firstName,
+    required String lastName,
+    required int age,
+  }) = _Person;
+
+  factory Person.fromJson(Map<String, Object?> json)
+      => _$PersonFromJson(json);
+}
+```
+
+```diff
+@freezed
+-class Model with _$Model {
++sealed class Model with _$Model {
+  factory Model.first(String a) = First;
+  factory Model.second(int b, bool c) = Second;
+}
+```
+
+### Pattern matching
+
+Freezed no longer generates `.map`/`.when` extensions and their derivatives for freezed classes used for pattern matching. Instead, use Dart's built-in [pattern matching](https://dart.dev/language/patterns#matching) syntax.
+
+```diff
+final model = Model.first('42');
+
+-final res = model.map(
+-  first: (String a) => 'first $a',
+-  second: (int b, bool c) => 'second $b $c',
+-);
++final res = switch (model) {
++  First(:final a) => 'first $a',
++  Second(:final b, :final c) => 'second $b $c',
++};
+
+```