Documentation schema for stream-events command
Add documentation for the current schema in use with the stream-events
command. This should allow other developers to write utilities that use
this functionality without having to look at the source code.
Added note that the schema may have any field blank or missing at any
time, so parsers should take that into consideration.
Change-Id: I582e3cfb093378dc2306f1e73fb1d844f6abdab1
diff --git a/Documentation/cmd-stream-events.txt b/Documentation/cmd-stream-events.txt
index cbd9246..3204641 100644
--- a/Documentation/cmd-stream-events.txt
+++ b/Documentation/cmd-stream-events.txt
@@ -34,10 +34,97 @@
-----
$ ssh -p 29418 review.example.com gerrit stream-events
- {"type":"comment-added","project":"tools/gerrit", ...}
- {"type":"comment-added","project":"tools/gerrit", ...}
+ {"type":"comment-added",change:{"project":"tools/gerrit", ...}, ...}
+ {"type":"comment-added",change:{"project":"tools/gerrit", ...}, ...}
-----
+SCHEMA
+------
+The JSON messages consist of nested objects referencing the *change*,
+*patchset*, *account* involved, and other attributes as appropriate.
+The currently supported message types are *patchset-added*,
+*comment-added*, *change-merged*, and *change-abandoned*.
+
+Note that any field may be missing in the JSON messages, so consumers of
+this JSON stream should deal with that appropriately.
+
+Events
+~~~~~~
+Patchset Added
+^^^^^^^^^^^^^^
+type:: "patchset-added"
+
+change:: <<change,change attribute>>
+
+patchset:: <<patchset,patchset attribute>>
+
+Change Abandoned
+^^^^^^^^^^^^^^^^
+type:: "change-abandoned"
+
+change:: <<change,change attribute>>
+
+patchset:: <<patchset,patchset attribute>>
+
+abandoner:: <<account,account attribute>>
+
+Change Merged
+^^^^^^^^^^^^^
+type:: "change-merged"
+
+change:: <<change,change attribute>>
+
+patchset:: <<patchset,patchset attribute>>
+
+submitter:: <<account,account attribute>>
+
+Comment Added
+^^^^^^^^^^^^^
+type:: "comment-added"
+
+change:: <<change,change attribute>>
+
+patchset:: <<patchset,patchset attribute>>
+
+author:: <<account,account attribute>>
+
+comment:: Comment text author had written
+
+Attributes
+~~~~~~~~~~
+Attributes are part events to give context related to the event.
+
+[[change]]
+change:: The Gerrit change the event is related to
+
+ project;; Project path in Gerrit
+
+ branch;; Branch name within project
+
+ id;; Change identifier
+
+ number;; Change number (deprecated)
+
+ subject;; Description of change
+
+ owner;; Owner in account attribute
+
+ url;; Canonical URL to reach this change
+
+[[account]]
+account:: An account that is related to an event or attribute
+
+ name;; Account user's full name
+
+ email;; Account user's preferred email
+
+[[patchset]]
+patchset:: Refers to a specific patchset within a change
+
+ number;; The patchset number
+
+ revision;; Git commit-ish for this patchset
+
SEE ALSO
--------
