Trace: add global_frame field to json-v1 format

Tools using the json-v1 format might want to trace stack frames across
different `CMakeLists.txt` files, in order to, for example, provide
stacktraces that span from the top-level `CMakeLists.txt` in a
project. One would think that `frame` lets you do that, but it
doesn't, because it tells you the depth of the stack within the
current `CMakeLists.txt`, so it gets reset across calls to
`add_subdirectory`.

The solution involves adding a field with a "global frame". This value
gets incremented on calls to `add_subdirectory`, which makes it easier
for tools to reconstruct "global stacktraces".

I considered changing the current "frame" value, but I didn't because
it would be a breaking change. I cannot think of any use-case where
"frame" is more useful to "global-frame", but maybe I'm missing
something.

1 files changed, 8 insertions, 0 deletions

diff --git a/Help/release/dev/trace-global-frame.rst b/Help/release/dev/trace-global-frame.rst
new file mode 100644
index 0000000..fdc4b5c
--- /dev/null
+++ b/Help/release/dev/trace-global-frame.rst
@@ -0,0 +1,8 @@
+trace-global-frame
+------------------
+
+* Add the field ``global_frame`` to the json-v1 trace format. This
+  frame tracks the depth of the call stack globally across all
+  ``CMakeLists.txt`` files involved in the trace, and will let tools
+  reconstruct stack traces that span from the top-level ``CMakeLists.txt``
+  file of the project.