docs: clarify trace2 version invariants
Make it explicit that we always want trace2 "version" events to be the first event of any trace session. Also list the changes that would or would not cause the EVENT format version field to be incremented. Signed-off-by: Josh Steadmon <steadmon@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Josh Steadmon committed
Oct 3, 2019 at 16:32 UTC
22541013d00bc457fe1fbdc8ac8b79edc069fd7e
1 file changed
+7
-1
Documentation/technical/api-trace2.txt
+7
-1
@@ -604,7 +604,13 @@ only present on the "start" and "atexit" events.
604
==== Event-Specific Key/Value Pairs
605
606
`"version"`::
607
- This event gives the version of the executable and the EVENT format.
607
+ This event gives the version of the executable and the EVENT format. It
608
+ should always be the first event in a trace session. The EVENT format
609
+ version will be incremented if new event types are added, if existing
610
+ fields are removed, or if there are significant changes in
611
+ interpretation of existing events or fields. Smaller changes, such as
612
+ adding a new field to an existing event, will not require an increment
613
+ to the EVENT format version.
614
+
615
------------
616
{