A complex type that contains the information for each change in a change batch request.
The data graph rooted below a Change can be quite complex:
{@link Change}| +- {@link ChangeMessage}: "cover letter" or general comment. | +- {@link PatchSet}: a single variant of this change. | +- {@link PatchSetApproval}: a +/- vote on the change's current state. | +- {@link PatchSetAncestor}: parents of this change's commit. | +- {@link PatchLineComment}: comment about a specific line
Every change has at least one PatchSet. A change starts out with one PatchSet, the initial proposal put forth by the change owner. This {@link Account} is usually also listed as the author and committer in thePatchSetInfo.
The {@link PatchSetAncestor} entities are a mirror of the Git commitmetadata, providing access to the information without needing direct accessing Git. These entities are actually legacy artifacts from Gerrit 1.x and could be removed, replaced by direct RevCommit access.
Each PatchSet contains zero or more Patch records, detailing the file paths impacted by the change (otherwise known as, the file paths the author added/deleted/modified). Sometimes a merge commit can contain zero patches, if the merge has no conflicts, or has no impact other than to cut off a line of development.
Each PatchLineComment is a draft or a published comment about a single line of the associated file. These are the inline comment entities created by users as they perform a review.
When additional PatchSets appear under a change, these PatchSets reference replacement commits; alternative commits that could be made to the project instead of the original commit referenced by the first PatchSet.
A change has at most one current PatchSet. The current PatchSet is updated when a new replacement PatchSet is uploaded. When a change is submitted, the current patch set is what is merged into the destination branch.
The ChangeMessage entity is a general free-form comment about the whole change, rather than PatchLineComment's file and line specific context. The ChangeMessage appears at the start of any email generated by Gerrit, and is shown on the change overview page, rather than in a file-specific context. Users often use this entity to describe general remarks about the overall concept proposed by the change.
PatchSetApproval entities exist to fill in the cells of the approvals table in the web UI. That is, a single PatchSetApproval record's key is the tuple {@code (PatchSet,Account,ApprovalCategory)}. Each PatchSetApproval carries with it a small score value, typically within the range -2..+2.
If an Account has created only PatchSetApprovals with a score value of 0, the Change shows in their dashboard, and they are said to be CC'd (carbon copied) on the Change, but are not a direct reviewer. This often happens when an account was specified at upload time with the {@code --cc} command line flag,or have published comments, but left the approval scores at 0 ("No Score").
If an Account has one or more PatchSetApprovals with a score != 0, the Change shows in their dashboard, and they are said to be an active reviewer. Such individuals are highlighted when notice of a replacement patch set is sent, or when notice of the change submission occurs.
| |