[llvm] [Docs][DebugInfo][RemoveDIs] Document some debug-info transition info (PR #79167)

[J. Ryan Stinnett via llvm-commits]

================
@@ -0,0 +1,106 @@
+# What's all this then?
+
+We're planning on removing debug info intrinsics from LLVM, as they're slow, unwieldy and can confuse optimisation passes if they're not expecting them. Instead of having a sequence of instructions that looks like this:
+
+```text
+    %add = add i32 %foo, %bar
+    call void @llvm.dbg.value(metadata %add, ...
+    %sub = sub i32 %add, %tosub
+    call void @llvm.dbg.value(metadata %sub, ...
+    call void @a_normal_function()
+```
+
+with dbg.value intrinsics representing debug info records, it would instead be printed as:
+
+```text
+    %add = add i32 %foo, %bar
+      #dbg_value(%add, ...
+    %sub = sub i32 %add, %tosub
+      #dbg_value(%sub, ...
+    call void @a_normal_function()
+```
+
+The debug records are not instructions, do not appear in the instruction list, and won't appear in your optimisation passes unless you go digging for them deliberately.
+
+# Great, what do I need to do!
+
+Approximately nothing -- we've already instrumented all of LLVM to handle these new records ("DPValues") and behave identically to past LLVM behaviour. We plan on turning this on by default some time soon, with IR converted to the intrinsic form of debug info at terminals (textual IR, bitcode) for a short while, before then changing the textual IR and bitcode formats.
----------------
jryans wrote:

```suggestion
Approximately nothing -- we've already instrumented all of LLVM to handle these new records ("`DPValues`") and behave identically to past LLVM behaviour. We plan on turning this on by default some time soon, with IR converted to the intrinsic form of debug info at terminals (textual IR, bitcode) for a short while, before then changing the textual IR and bitcode formats.
```

https://github.com/llvm/llvm-project/pull/79167