Merge pull request #12219 from greg0ire/rework-upgrade-md

Move introduction outside of paragraph about 3.x

Author: greg0ire

UPGRADE.md

@@ -1,3 +1,11 @@
+Note about upgrading: Doctrine uses static and runtime mechanisms to raise
+awareness about deprecated code.
+
+- Use of `@deprecated` docblock that is detected by IDEs (like PHPStorm) or
+  Static Analysis tools (like Psalm, phpstan)
+- Use of our low-overhead runtime deprecation API, details:
+  https://github.com/doctrine/deprecations/
+
 # Upgrade to 3.x General Notes
 
 We recommend you upgrade to DBAL 3 first before upgrading to ORM 3. See
@@ -19,14 +27,6 @@ At this point, we recommend upgrading to PHP 8.4 first and then directly from
 ORM 2.19 to 3.5 and up so that you can skip the lazy ghost proxy generation
 and directly start using native lazy objects.
 
-Note about upgrading: Doctrine uses static and runtime mechanisms to raise
-awareness about deprecated code.
-
-- Use of `@deprecated` docblock that is detected by IDEs (like PHPStorm) or
-  Static Analysis tools (like Psalm, phpstan)
-- Use of our low-overhead runtime deprecation API, details:
-  https://github.com/doctrine/deprecations/
-
 # Upgrade to 3.5
 
 See the General notes to upgrading to 3.x versions above.