[DOCS][UX3] Start an UPGRADE file

We can either work with branch or merge it in the 3.x branch
(and then update it along the way)

I'd rather do the "merge" one but open to opinions here

along the wa

Author: smnandre

UPGRADE-3.0.md

@@ -0,0 +1,87 @@
+# UPGRADE FROM `2.x` TO `3.0`
+
+Symfony UX follows Symfony's release system. This means that major
+versions (like `3.0`) offer the same functionality as their previous minor
+versions (like `2.x`), once all deprecations have been removed.
+
+However, major versions may also introduce new features and improvements, and a
+bump in the required PHP or packages versions.
+
+---
+
+## Table of Contents
+
+* [Requirements](#requirements)
+  * [UX 3.0](#ux-30)
+  * [UX 3.x](#ux-3x)
+* [Packages](#packages)
+  * [Twig Component](#twig-component)
+* [Removed Packages](#removed-packages)
+  * [LazyImage (removed)](#lazyimage-removed)
+  * [Swup (removed)](#swup-removed)
+  * [TogglePassword (removed)](#togglepassword-removed)
+  * [Typed (removed)](#typed-removed)
+
+---
+
+## Requirements
+
+### UX 3.0
+
+- Requires PHP `8.1` or higher.
+- Requires Symfony `6.4` or higher.
+
+### UX 3.x
+
+- New features or packages introduced in future `3.x` releases may require
+  higher versions of PHP (e.g. `8.2`, `8.3`) and/or Symfony (e.g. `7.x`).
+
+[[Back to top]](#table-of-contents)
+
+---
+
+## Packages
+
+### Twig Component
+
+- Install `twig/html-extra` if you are using the `cva` function. You may need
+  to update the signature of the `cva()` Twig function in your templates to
+  match the new signature.
+
+[[Back to top]](#table-of-contents)
+
+---
+
+## Removed Packages
+
+> [!IMPORTANT]
+> The packages deprecated in `2.x` and have been removed in `3.0`.
+>
+> They remain usable in the `2.x` branch, but should be avoided in new projects,
+> as they will not be maintained going forward. See below for details.
+
+### LazyImage (removed)
+
+* Deprecated in `2.x` and **removed in `3.0`**. Use the native `loading="lazy"`
+  attribute on `<img>` elements instead. See the [previous README](https://raw.githubusercontent.com/symfony/ux/refs/heads/2.x/src/LazyImage/README.md)
+  for reference.
+
+### Swup (removed)
+
+* Deprecated in `2.x` and **removed in `3.0`**. Use Turbo and CSS-based page
+  transitions instead. See the [previous README](https://raw.githubusercontent.com/symfony/ux/refs/heads/2.x/src/Swup/README.md)
+  for reference.
+
+### TogglePassword (removed)
+
+* Deprecated in `2.x` and **removed in `3.0`**. Use a custom user-land
+  implementation instead. See the [previous README](https://raw.githubusercontent.com/symfony/ux/refs/heads/2.x/src/TogglePassword/README.md)
+  for reference.
+
+### Typed (removed)
+
+* Deprecated in `2.x` and **removed in `3.0`**. Use a custom user-land
+  implementation instead. See the [previous README](https://raw.githubusercontent.com/symfony/ux/refs/heads/2.x/src/Typed/README.md)
+  for reference.
+
+[[Back to top]](#table-of-contents)