Index: llvm/docs/OngoingMajorChanges.rst
===================================================================
--- /dev/null
+++ llvm/docs/OngoingMajorChanges.rst
@@ -0,0 +1,77 @@
+=====================
+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
+branches 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