docs: update release notes and upgrade guide for v3 breaking changes

Author: fgmacedo

docs/releases/3.0.0.md

@@ -486,3 +486,20 @@ The `allow_event_without_transition` was previously configured as an init parame
 attribute.
 
 Defaults to `False` in `StateMachine` class to preserve maximum backwards compatibility.
+
+
+### `States.from_enum` default `use_enum_instance=True`
+
+The `use_enum_instance` parameter of `States.from_enum` now defaults to `True` (was `False` in 2.x).
+This means state values are the enum instances themselves, not their raw values.
+
+If your code relies on raw enum values (e.g., integers), pass `use_enum_instance=False` explicitly.
+
+
+### Short registry names removed
+
+State machine classes are now only registered by their fully-qualified name (`qualname`).
+The short-name lookup (by `cls.__name__`) that was deprecated since v0.8 has been removed.
+
+If you use `get_machine_cls()` (e.g., via `MachineMixin`), make sure you pass the fully-qualified
+dotted path.

docs/releases/upgrade_2x_to_3.md

@@ -17,6 +17,8 @@ defaults. Review this guide to understand what changed and adopt the new APIs at
 5. Replace `sm.add_observer(...)` with `sm.add_listener(...)`.
 6. Update code that catches `TransitionNotAllowed` and accesses `.state` → use `.configuration`.
 7. Review `on` callbacks that query `is_active` or `current_state` during transitions.
+8. If using `States.from_enum`, note that `use_enum_instance` now defaults to `True`.
+9. If using `get_machine_cls()` with short names, switch to fully-qualified names.
 
 ---
 
@@ -174,6 +176,51 @@ sm.add_listener(my_listener)
 ```
 
 
+## `States.from_enum` default changed to `use_enum_instance=True`
+
+In 2.x, `States.from_enum` defaulted to `use_enum_instance=False`, meaning state values were the
+raw enum values (e.g., integers). In 3.0, the default is `True`, so state values are the enum
+instances themselves.
+
+**Before (2.x):**
+
+```python
+states = States.from_enum(MyEnum, initial=MyEnum.start)
+# states.start.value == 1  (raw value)
+```
+
+**After (3.0):**
+
+```python
+states = States.from_enum(MyEnum, initial=MyEnum.start)
+# states.start.value == MyEnum.start  (enum instance)
+```
+
+If your code relies on raw enum values, pass `use_enum_instance=False` explicitly.
+
+
+## Short registry names removed
+
+In 2.x, state machine classes were registered both by their fully-qualified name and their short
+class name. The short-name lookup was deprecated since v0.8 and has been removed in 3.0.
+
+**Before (2.x):**
+
+```python
+from statemachine.registry import get_machine_cls
+
+cls = get_machine_cls("MyMachine")  # short name — worked with warning
+```
+
+**After (3.0):**
+
+```python
+from statemachine.registry import get_machine_cls
+
+cls = get_machine_cls("myapp.machines.MyMachine")  # fully-qualified name
+```
+
+
 ## Update `TransitionNotAllowed` exception handling
 
 The `TransitionNotAllowed` exception now stores a `configuration` attribute (a set of states)