[flang-commits] [flang] 435957a - [flang][docs] Removed HighLevelFIR transition plan section (#196227)

[via flang-commits]

Author: Eugene Epshteyn
Date: 2026-05-08T15:51:14Z
New Revision: 435957ac1c05a9fe7c21cea947d04774d60484c9

URL: https://github.com/llvm/llvm-project/commit/435957ac1c05a9fe7c21cea947d04774d60484c9
DIFF: https://github.com/llvm/llvm-project/commit/435957ac1c05a9fe7c21cea947d04774d60484c9.diff

LOG: [flang][docs] Removed HighLevelFIR transition plan section (#196227)

Removed the "Transition Plan" section from flang/docs/HighLevelFIR.md,
since the transition has completed a long time ago and the legacy
lowering code is being removed now.

Added: 
    flang/docs/HLFIRTransition.md

Modified: 
    flang/docs/HighLevelFIR.md
    flang/docs/index.md

Removed: 
    


################################################################################
diff  --git a/flang/docs/HLFIRTransition.md b/flang/docs/HLFIRTransition.md
new file mode 100644
index 0000000000000..b63af78fee1dd
--- /dev/null
+++ b/flang/docs/HLFIRTransition.md
@@ -0,0 +1,55 @@
+# Transition of Lowering to HLFIR
+
+This section was extracted from [HighLevelFIR.md](High-Level Fortran IR (HLFIR)). 
+This information is no longer relevant to the current state of HLFIR
+lowering, but could be useful as a historical reference.
+
+## Transition Plan
+
+The new higher-level steps proposed in this document will require significant
+refactoring of lowering. Codegen should not be impacted since the current FIR
+will remain untouched.
+
+A lot of the code in lowering generating Fortran features (like an intrinsic or
+how to do assignments) is based on the fir::ExtendedValue concept. This
+currently is a collection of mlir::Value that allows describing a Fortran object
+(either a variable or an evaluated expression result). The variable and
+expression concepts described above should allow to keep an interface very
+similar to the fir::ExtendedValue, but having the fir::ExtendedValue wrap a
+single value or mlir::Operation* from which all of the object entity
+information can be inferred.
+
+That way, all the helpers currently generating FIR from fir::ExtendedValue could
+be kept and used with the new variable and expression concepts with as little
+modification as possible.
+
+The proposed plan is to:
+- 1. Introduce the new HLFIR operations.
+- 2. Refactor fir::ExtendedValue so that it can work with the new variable and
+     expression concepts (requires part of 1.).
+- 3. Introduce the new translation passes, using the fir::ExtendedValue helpers
+     (requires 1.).
+- 3.b Introduce the new optimization passes (requires 1.).
+- 4. Introduce the fir.declare and hlfir.finalize usage in lowering (requires 1.
+     and 2. and part of 3.).
+
+The following steps might have to be done in parallel of the current lowering,
+to avoid disturbing the work on performance until the new lowering is complete
+and on par.
+
+- 5. Introduce hlfir.designate and hlfir.associate usage in lowering.
+- 6. Introduce lowering to hlfir.assign (with RHS that is not a hlfir.expr),
+     hlfir.ptr_assign.
+- 7. Introduce lowering to hlfir.expr and related operations.
+- 8. Introduce lowering to hlfir.forall.
+
+At that point, lowering using the high-level FIR should be in place, allowing
+extensive testing.
+- 9. Debugging correctness.
+- 10. Debugging execution performance.
+
+The plan is to do these steps incrementally upstream, but for lowering this will
+most likely be safer to do have the new expression lowering implemented in
+parallel upstream, and to add an option to use the new lowering rather than to
+directly modify the current expression lowering and have it step by step
+equivalent functionally and performance wise.

diff  --git a/flang/docs/HighLevelFIR.md b/flang/docs/HighLevelFIR.md
index 2399efcdeacd3..99a05c48b1e4e 100644
--- a/flang/docs/HighLevelFIR.md
+++ b/flang/docs/HighLevelFIR.md
@@ -960,56 +960,6 @@ LLVM.
 These high level optimization passes can be run any number of times in any
 order.
 
-## Transition Plan
-
-The new higher-level steps proposed in this document will require significant
-refactoring of lowering. Codegen should not be impacted since the current FIR
-will remain untouched.
-
-A lot of the code in lowering generating Fortran features (like an intrinsic or
-how to do assignments) is based on the fir::ExtendedValue concept. This
-currently is a collection of mlir::Value that allows describing a Fortran object
-(either a variable or an evaluated expression result). The variable and
-expression concepts described above should allow to keep an interface very
-similar to the fir::ExtendedValue, but having the fir::ExtendedValue wrap a
-single value or mlir::Operation* from which all of the object entity
-information can be inferred.
-
-That way, all the helpers currently generating FIR from fir::ExtendedValue could
-be kept and used with the new variable and expression concepts with as little
-modification as possible.
-
-The proposed plan is to:
-- 1. Introduce the new HLFIR operations.
-- 2. Refactor fir::ExtendedValue so that it can work with the new variable and
-     expression concepts (requires part of 1.).
-- 3. Introduce the new translation passes, using the fir::ExtendedValue helpers
-     (requires 1.).
-- 3.b Introduce the new optimization passes (requires 1.).
-- 4. Introduce the fir.declare and hlfir.finalize usage in lowering (requires 1.
-     and 2. and part of 3.).
-
-The following steps might have to be done in parallel of the current lowering,
-to avoid disturbing the work on performance until the new lowering is complete
-and on par.
-
-- 5. Introduce hlfir.designate and hlfir.associate usage in lowering.
-- 6. Introduce lowering to hlfir.assign (with RHS that is not a hlfir.expr),
-     hlfir.ptr_assign.
-- 7. Introduce lowering to hlfir.expr and related operations.
-- 8. Introduce lowering to hlfir.forall.
-
-At that point, lowering using the high-level FIR should be in place, allowing
-extensive testing.
-- 9. Debugging correctness.
-- 10. Debugging execution performance.
-
-The plan is to do these steps incrementally upstream, but for lowering this will
-most likely be safer to do have the new expression lowering implemented in
-parallel upstream, and to add an option to use the new lowering rather than to
-directly modify the current expression lowering and have it step by step
-equivalent functionally and performance wise.
-
 ## Examples
 
 ### Example 1: simple array assignment

diff  --git a/flang/docs/index.md b/flang/docs/index.md
index 029f49a353d8f..a565b15528642 100644
--- a/flang/docs/index.md
+++ b/flang/docs/index.md
@@ -105,6 +105,15 @@ on how to get in touch with us and to learn more about the current status.
    fstack-arrays
 ```
 
+# Historical References
+
+```{eval-rst}
+.. toctree::
+   :titlesonly:
+
+   HLFIRTransition
+```
+
 # Indices and tables
 
 ```{eval-rst}