skcq/go/codereview/codereview.go

package codereview

import (
	"context"

	"go.skia.org/infra/go/gerrit"
)

// Interface to abstract out SkCQ communications with gerrit client and
// provide utility methods.
type CodeReview interface {

	// AddComments adds a comment to the specified change using the
	// AutogeneratedCommentTag.
	AddComment(ctx context.Context, ci *gerrit.ChangeInfo, comment string, notify NotifyOption, notifyReason string) error

	// GetChangeRef returns the change's ref string. A change ref has the format
	// refs/changes/X/Y/Z where X is the last two digits of the change number,
	// Y is the entire change number, and Z is the patch set.
	// Eg: For change 401222 and patchset 140, the change ref would be:
	//     refs/changes/22/401222/140
	GetChangeRef(ci *gerrit.ChangeInfo) string

	// GetCommitAuthor retrieves the author of the commit that corresponds to
	// the patch identified by issue and revision.
	GetCommitAuthor(ctx context.Context, issue int64, revision string) (string, error)

	// GetCommitMessage returns the commit msg of this change. Note: this returns
	// the commit msg on the latest patchset.
	GetCommitMessage(ctx context.Context, issue int64) (string, error)

	// GetEarliestEquialentPatchSetID returns the earliest patchset that is
	// functionally equivalent to the latest patchset (i.e. not a CODE_CHANGE
	// patchset).
	GetEarliestEquivalentPatchSetID(ci *gerrit.ChangeInfo) int64

	// GetEquivalentPatchSetIDs returns a slice of patchsetIDs that are
	// functionally equivalent to the specified patchset (i.e. not a
	// CODE_CHANGE patchset).
	GetEquivalentPatchSetIDs(ci *gerrit.ChangeInfo, patchsetID int64) []int64

	// GetFileNames returns all the files modified (A/D/M) by this change.
	GetFileNames(ctx context.Context, ci *gerrit.ChangeInfo) ([]string, error)

	// GetIssueProperties returns a fully filled in gerrit.ChangeInfo object.
	GetIssueProperties(ctx context.Context, issue int64) (*gerrit.ChangeInfo, error)

	// GetLatestPatchSetID returns the patchsetID of the latest patchset.
	GetLatestPatchSetID(ci *gerrit.ChangeInfo) int64

	// GetSubmittedTogether returns the list of changes that will be submitted
	// at the same time as the given change. Note: The specified change will not
	// be included in the returned slice of changes.
	// The returned ChangeInfo objects are fully filled in.
	GetSubmittedTogether(ctx context.Context, ci *gerrit.ChangeInfo) ([]*gerrit.ChangeInfo, error)

	// IsCQ returns whether the specified change is a CQ run.
	IsCQ(ctx context.Context, ci *gerrit.ChangeInfo) bool

	// IsDryRun returns whether the specified change is a dry run.
	IsDryRun(ctx context.Context, ci *gerrit.ChangeInfo) bool

	// RemoveFromCQ removes all CQ+1/CQ+2 votes on a change and updates the
	// change with the specified message.
	RemoveFromCQ(ctx context.Context, ci *gerrit.ChangeInfo, comment string, notifyReason string)

	// Search returns open changes with CQ+2 or CQ+1 votes set.
	// Note: This returns gerrit.ChangeInfo that are incomplete. Call
	// GetIssueProperties to populate them.
	Search(ctx context.Context) ([]*gerrit.ChangeInfo, error)

	// SetReadyForReview publishes the specified change. i.e. it sets it from
	// WIP to ready for reaview.
	SetReadyForReview(ctx context.Context, ci *gerrit.ChangeInfo) error

	// Submit submits the specifed change.
	Submit(ctx context.Context, ci *gerrit.ChangeInfo) error

	// Url returns the url of the issue identified by issueID or the
	// base URL of the Gerrit instance if issueID is 0.
	Url(issueID int64) string

	// GetRepoUrl returns the url of the Googlesource repo.
	GetRepoUrl(ci *gerrit.ChangeInfo) string

	// GetCQVoters returns all CQ label voters.
	GetCQVoters(ctx context.Context, ci *gerrit.ChangeInfo) []string
}

// NotifyOption are the different notification options supported by SkCQ.
type NotifyOption string

const NotifyNone NotifyOption = "NONE"
const NotifyOwnerTriggerers NotifyOption = "OWNER_TRIGGERERS"
const NotifyOwnerReviewersTriggerers NotifyOption = "OWNER_REVIEWERS_TRIGGERERS"