[flang-commits] [flang] [flang][docs] Mark HighLevelFIR transition plan as historical (PR #196227)

[Eugene Epshteyn via flang-commits]

https://github.com/eugeneepshteyn created https://github.com/llvm/llvm-project/pull/196227

Rewrite the "Transition Plan" section in flang/docs/HighLevelFIR.md as "Transition (Historical)". HLFIR is now the only lowering path, and the opt-in driver flag plus the legacy FIR-only expression lowering have been removed, so the section no longer describes pending work. Convert the steps to past tense, drop the "current lowering" framing, and add a short note explaining how the transition concluded.

>From d6eac83845d23c8fd3103a3382aa34e0b54e6ca8 Mon Sep 17 00:00:00 2001
From: Eugene Epshteyn <eepshteyn at nvidia.com>
Date: Wed, 6 May 2026 23:28:03 -0400
Subject: [PATCH] [flang][docs] Mark HighLevelFIR transition plan as historical

Rewrite the "Transition Plan" section in flang/docs/HighLevelFIR.md as
"Transition (Historical)". HLFIR is now the only lowering path, and the
opt-in driver flag plus the legacy FIR-only expression lowering have
been removed, so the section no longer describes pending work. Convert
the steps to past tense, drop the "current lowering" framing, and add a
short note explaining how the transition concluded.
---
 flang/docs/HighLevelFIR.md | 87 +++++++++++++++++---------------------
 1 file changed, 38 insertions(+), 49 deletions(-)

diff --git a/flang/docs/HighLevelFIR.md b/flang/docs/HighLevelFIR.md
index 2399efcdeacd3..28fbc9bb531ab 100644
--- a/flang/docs/HighLevelFIR.md
+++ b/flang/docs/HighLevelFIR.md
@@ -960,55 +960,44 @@ 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.
+## Transition (Historical)
+
+HLFIR is now the only lowering path; the legacy FIR-only expression lowering
+and the options that selected it have been removed. This section is kept for
+historical reference.
+
+The introduction of HLFIR required significant refactoring of lowering, but
+codegen was unaffected because the underlying FIR pipeline was preserved.
+
+Most lowering helpers were built around the `fir::ExtendedValue` concept --
+a collection of `mlir::Value`s describing a Fortran object (variable or
+evaluated expression result). The variable and expression concepts above
+allowed keeping a similar interface, with `fir::ExtendedValue` wrapping a
+single value or `mlir::Operation *` from which all object information could
+be inferred, so existing helpers carried over with minimal modification.
+
+The transition proceeded in roughly the following order:
+
+1. Introduce the new HLFIR operations.
+2. Refactor `fir::ExtendedValue` to 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 `fir.declare` and `hlfir.finalize` usage in lowering (requires
+   1, 2, and part of 3).
+5. Introduce `hlfir.designate` and `hlfir.associate` usage in lowering.
+6. Introduce lowering to `hlfir.assign` (with RHS that is not an `hlfir.expr`)
+   and `hlfir.ptr_assign`.
+7. Introduce lowering to `hlfir.expr` and related operations.
+8. Introduce lowering to `hlfir.forall`.
+9. Debug correctness.
+10. Debug execution performance.
+
+Steps 5-10 were done with the new lowering implemented alongside the old one
+behind an opt-in driver flag, so performance work on the legacy path was not
+disturbed until the new lowering reached parity. Once HLFIR was on by
+default, the opt-in flag and the legacy expression lowering were removed.
 
 ## Examples