Index: llvm/docs/OngoingMajorChanges.rst
===================================================================
--- /dev/null
+++ llvm/docs/OngoingMajorChanges.rst
@@ -0,0 +1,52 @@
+=====================
+Ongoing Major Changes
+=====================
+
+The LLVM intermediate representation, as well as the LLVM project
+infrastructure, are continuously evolving. Some changes are complex and
+happen over the span of many years.
+
+This page documents ongoing major changes and their current status.
+
+Opaque Pointers
+===============
+
+LLVM is moving away from typed pointers (``i8*``) towards opaque pointers (``ptr``), which do not have a pointer element type. New code should avoid inspecting pointer element types (do not call ``getPointerElementType()``) and instead inspect semantically relevant types, such as load or store types.
+
+Documentation is available at :doc:`OpaquePointers`.
+
+Transition status: Support for opaque pointers in LLVM and Clang is close to complete. LLVM 15 will enable opaque pointers by default, but retain support for typed pointers. Typed pointer support will be removed after the LLVM 15 release branch.
+
+New Pass Manager
+================
+
+LLVM is moving towards a new pass manager, which permits more efficient pass and analysis scheduling.
+
+Documentation is available at :doc:`NewPassManager`.
+
+Transition status: The new pass manager is enabled by default since LLVM 13. Support for the legacy pass manager in the middle-end optimization pipeline is planned to be removed in LLVM 15. The backend optimization pipeline continues using the legacy pass manager for the time being.
+
+GlobalISel
+==========
+
+LLVM is moving towards a new instruction selector, which replaces both SelectionDAG and FastISel. It works on the whole function rather than a single basic block, and operates directly on MIR.
+
+Documentation is available at :doc:`GlobalISel/index`, which has multiple sub-pages.
+
+Transition status: Some backends like AArch64 use GlobalISel for code generation at ``O0`` (replacing FastISel). However, there has been no effort towards migrating all backends, and there are currently no specific plans to remove SelectionDAG or FastISel.
+
+Poison Values
+=============
+
+LLVM is moving from undef values towards poison values. Poison values permit more optimizations and have much simpler semantics. Code and tests should prefer using poison wherever possible.
+
+Documentation is available at :ref:`poisonvalues`.
+
+Transition status: Large parts of LLVM have already moved towards using poison values, but there are still some operations that are specified to return undef on "failure". The most important are loads from uninitialized memory, which are tracked at `issue #52930 <https://github.com/llvm/llvm-project/issues/52930>`_.
+
+Branch on Undef/Poison
+======================
+
+The LLVM language reference specifies that branching on undef or poison is immediate undefined behavior. However, there are currently some optimizations that can introduce new branches on poison/undef. For that reason, we currently do not exploit this undefined behavior in most optimizations.
+
+Transition status: There are still a number of optimizations introducing branch on poison, with SimpleLoopUnswitch being the most important one.
Index: llvm/docs/UserGuides.rst
===================================================================
--- llvm/docs/UserGuides.rst
+++ llvm/docs/UserGuides.rst
@@ -45,6 +45,7 @@
    MergeFunctions
    MCJITDesignAndImplementation
    ORCv2
+   OngoingMajorChanges
    OpaquePointers
    JITLink
    NewPassManager