opendev/gerrit
Code Issues Proposed changes
65dba820d4
gerrit/Documentation/json.txt
Khai Do 71b58990e9 Append approval info to every comment-added stream event and hook 
This change is driven by the RFC proposal[1] to show label
transitions more explicitly in Gerrit. Stream events only
provides label information on review events that contain
a vote transition.  When a user submits a review with only a
reply message the approvals information is not added to the
stream event and hooks. This change will make Gerrit append
approvals info to every comment-added event including the
ones that do not contain vote changes.

Since labels are shown for every event we will add an 'oldValue'
property to the approvalAttribute to distinguish when a vote
transition has occurred.  The 'oldValue' attribute contains
the previous vote score.  This attribute will only appear when
there is a vote transition.

The comment-added stream event will look like this:

  "approvals":[{"type":"Code-Review","description":"Code-Review",
  "value":"-1", "oldValue":"0"}, {"type":"Verified",
  "description":"Verified","value":"0"}],
  "comment":"Patch Set 1: Code-Review+1\n\nMy Message" ...

This change will also a '--$LabelName-oldValue' parameter to
corresponding comment-added change hook:

  hook[comment-added] output:
  --change I2cd8327360ff89338a4e7f0591bf0c037e9aa5db
  --is-draft false --change-url http://localhost:8080/201
  --change-owner John Smith (jsmith@gmail.com) --project okc
  --branch master --author John Smith (jsmith@gmail.com)
  --commit 55079187f7ce1c461de804c13f2dd71d64a85280
  --comment Patch Set 1: Code-Review-1 --Code-Review -1
  --Code-Review-oldValue 0 --Verified 0

[1] https://groups.google.com/d/msg/repo-discuss/soqmGjRpl-4/IIfAF4jbCQAJ

Bug: Issue 3220
Change-Id: Ibc1c64d70e790c7b507db79931f31fd77f25e276
2016-03-18 14:47:36 +01:00

275 lines
7.3 KiB
Plaintext
Raw Blame History

= Gerrit Code Review - JSON Data
Some commands produce JSON data streams intended for other
applications to consume. The structures are documented below.
Note that any field may be missing in the JSON messages, so consumers
of this JSON stream should deal with that appropriately.
[[change]]
== change
The Gerrit change being reviewed, or that was already reviewed.
project:: Project path in Gerrit.
branch:: Branch name within project.
topic:: Topic name specified by the uploader for this change series.
id:: Change identifier, as scraped out of the Change-Id field in
the commit message, or as assigned by the server if it was missing.
number:: Change number (deprecated).
subject:: Description of change.
owner:: Owner in <<account,account attribute>>.
url:: Canonical URL to reach this change.
commitMessage:: The full commit message for the change's current patch
set.
createdOn:: Time in seconds since the UNIX epoch when this change
was created.
lastUpdated:: Time in seconds since the UNIX epoch when this change
was last updated.
open:: Boolean indicating if the change is still open for review.
status:: Current state of this change.
NEW;; Change is still being reviewed.
DRAFT;; Change is a draft change that only consists of draft patchsets.
MERGED;; Change has been merged to its branch.
ABANDONED;; Change was abandoned by its owner or administrator.
comments:: All inline/file comments for this change in <<message,message attributes>>.
trackingIds:: Issue tracking system links in
<<trackingid,trackingid attributes>>, scraped out of the commit
message based on the server's
link:config-gerrit.html#trackingid[trackingid] sections.
currentPatchSet:: Current <<patchSet,patchSet attribute>>.
patchSets:: All <<patchSet,patchSet attributes>> for this change.
dependsOn:: List of changes that this change depends on in <<dependency,dependency attributes>>.
neededBy:: List of changes that depend on this change in <<dependency,dependency attributes>>.
submitRecords:: The <<submitRecord,submitRecord attribute>> contains
information about whether this change has been or can be submitted.
allReviewers:: List of all reviewers in <<account,account attribute>>
which are added to a change.
[[trackingid]]
== trackingid
A link to an issue tracking system.
system:: Name of the system. This comes straight from the
gerrit.config file.
id:: Id number as scraped out of the commit message.
[[account]]
== account
A user account.
name:: User's full name, if configured.
email:: User's preferred email address.
username:: User's username, if configured.
[[patchSet]]
== patchSet
Refers to a specific patchset within a <<change,change>>.
number:: The patchset number.
revision:: Git commit for this patchset.
parents:: List of parent revisions.
ref:: Git reference pointing at the revision. This reference is
available through the Gerrit Code Review server's Git interface
for the containing change.
uploader:: Uploader of the patch set in <<account,account attribute>>.
author:: Author of this patchset in <<account,account attribute>>.
createdOn:: Time in seconds since the UNIX epoch when this patchset
was created.
isDraft:: Whether or not the patch set is a draft patch set.
kind:: Kind of change uploaded.
REWORK;; Nontrivial content changes.
TRIVIAL_REBASE;; Conflict-free merge between the new parent and the prior patch set.
NO_CODE_CHANGE;; No code changed; same tree and same parent tree.
NO_CHANGE;; No changes; same commit message, same tree and same parent tree.
approvals:: The <<approval,approval attribute>> granted.
comments:: All comments for this patchset in <<patchsetcomment,patchsetComment attributes>>.
files:: All changed files in this patchset in <<file,file attributes>>.
sizeInsertions:: Size information of insertions of this patchset.
sizeDeletions:: Size information of deletions of this patchset.
[[approval]]
== approval
Records the code review approval granted to a patch set.
type:: Internal name of the approval given.
description:: Human readable category of the approval.
value:: Value assigned by the approval, usually a numerical score.
oldValue:: The previous approval score, only present if the value changed as a result of this event.
grantedOn:: Time in seconds since the UNIX epoch when this approval
was added or last updated.
by:: Reviewer of the patch set in <<account,account attribute>>.
[[refUpdate]]
== refUpdate
Information about a ref that was updated.
oldRev:: The old value of the ref, prior to the update.
newRev:: The new value the ref was updated to.
refName:: Full ref name within project.
project:: Project path in Gerrit.
[[submitRecord]]
== submitRecord
Information about the submit status of a change.
status:: Current submit status.
OK;; The change is ready for submission or already submitted.
NOT_READY;; The change is missing a required label.
RULE_ERROR;; An internal server error occurred preventing computation.
labels:: This describes the state of each code review
<<label,label attribute>>, unless the status is RULE_ERROR.
[[label]]
== label
Information about a code review label for a change.
label:: The name of the label.
status:: The status of the label.
OK;; This label provides what is necessary for submission.
REJECT;; This label prevents the change from being submitted.
NEED;; The label is required for submission, but has not
been satisfied.
MAY;; The label may be set, but it's neither necessary for
submission nor does it block submission if set.
IMPOSSIBLE;; The label is required for submission, but is impossible
to complete. The likely cause is access has not been granted
correctly by the project owner or site administrator.
by:: The <<account,account>> that applied the label.
[[dependency]]
== dependency
Information about a change or patchset dependency.
id:: Change identifier.
number:: Change number.
revision:: Patchset revision.
ref:: Ref name.
isCurrentPatchSet:: If the revision is the current patchset of the change.
[[message]]
== message
Comment added on a change by a reviewer.
timestamp:: Time in seconds since the UNIX epoch when this comment
was added.
reviewer:: The <<account,account>> that added the comment.
message:: The comment text.
[[patchsetcomment]]
== patchsetComment
Comment added on a patchset by a reviewer.
file:: The name of the file on which the comment was added.
line:: The line number at which the comment was added.
reviewer:: The <<account,account>> that added the comment.
message:: The comment text.
[[file]]
== file
Information about a patch on a file.
file:: The name of the file. If the file is renamed, the new name.
fileOld:: The old name of the file, if the file is renamed.
type:: The type of change.
ADDED;; The file is being created/introduced by this patch.
MODIFIED;; The file already exists, and has updated content.
DELETED;; The file existed, but is being removed by this patch.
RENAMED;; The file is renamed.
COPIED;; The file is copied from another file.
REWRITE;; Sufficient amount of content changed to claim the file was rewritten.
insertions:: number of insertions of this patch.
deletions:: number of deletions of this patch.
== SEE ALSO
* link:cmd-stream-events.html[gerrit stream-events]
* link:cmd-query.html[gerrit query]
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------
View Git Blame Copy Permalink