docs: clarify trace2 version invariants

steadmon · gitster · commit 22541013d00b · 2019-10-04T09:26:42.000+09:00
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 &lt;steadmon@google.com&gt;
Signed-off-by: Junio C Hamano &lt;gitster@pobox.com&gt;
diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt
@@ -604,7 +604,13 @@ only present on the "start" and "atexit" events.
 ==== Event-Specific Key/Value Pairs
 
 `"version"`::
-	This event gives the version of the executable and the EVENT format.
+	This event gives the version of the executable and the EVENT format. It
+	should always be the first event in a trace session. The EVENT format
+	version will be incremented if new event types are added, if existing
+	fields are removed, or if there are significant changes in
+	interpretation of existing events or fields. Smaller changes, such as
+	adding a new field to an existing event, will not require an increment
+	to the EVENT format version.
 +
 ------------
 {

Original file line number	Diff line number	Diff line change
`@@ -604,7 +604,13 @@ only present on the "start" and "atexit" events.`
`604`	`604`	`==== Event-Specific Key/Value Pairs`
`605`	`605`
`606`	`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.`
`608`	`614`	`+`
`609`	`615`	`------------`
`610`	`616`	`{`