cancel

Documentation

Overview

Package cancel implements cancelling triggers of Run by removing CQ Votes on a CL.

Index

• Variables
• func Cancel(ctx context.Context, gFactory gerrit.ClientFactory, in Input) error
• type Input
• type Notify

Variables

var ErrPermanentTag = errors.BoolTag{
	Key: errors.NewTagKey("permanent error while cancelling triggers"),
}

ErrPermanentTag is an error tag indicating that error occurs during the cancellation is permanent (e.g. lack of vote permission).

var ErrPreconditionFailedTag = errors.BoolTag{
	Key: errors.NewTagKey("cancel precondition not met"),
}

ErrPreconditionFailedTag is an error tag indicating that Cancel precondition failed.

Functions

func Cancel

func Cancel(ctx context.Context, gFactory gerrit.ClientFactory, in Input) error

Cancel removes or "deactivates" CQ-triggering votes on a CL and posts the given message.

Returns error tagged with `ErrPreconditionFailedTag` if one of the following conditions is matched.

• The patchset of the provided CL is not the latest in Gerrit.
• The provided CL gets `changelist.AccessDenied` or `changelist.AccessDeniedProbably` from Gerrit.

Normally, the triggering vote(s) is removed last and all other votes are removed in chronological order (latest to earliest). After all votes are removed, the message is posted to Gerrit.

Abnormally, e.g. lack of permission to remove votes, falls back to post a special message which "deactivates" the triggering votes. This special message is a combination of:

• the original message in the input
• reason for abnormality,
• special `botdata.BotData` which ensures CV won't consider previously triggering votes as triggering in the future.

Types

type Input

type Input struct {
	// CL is a Gerrit CL entity.
	//
	// Must have CL.Snapshot set.
	CL *changelist.CL
	// Trigger identifies the triggering vote. Required.
	//
	// Removed only after all other votes on CQ label are removed.
	Trigger *run.Trigger
	// LUCIProject is the project that initiates this cancellation.
	//
	// The project scoped account of this LUCI project SHOULD have the permission
	// to set the CQ label on behalf of other users in Gerrit.
	LUCIProject string
	// Message to be posted along with the triggering vote removal
	Message string
	// Requester describes the caller (e.g. Project Manager, Run Manager).
	Requester string
	// Notify describes whom to notify regarding the cancellation.
	//
	// Example: OWNER|REVIEWERS|VOTERS
	Notify Notify
	// LeaseDuration is how long a lease will be held for this cancellation.
	//
	// If the passed context has a closer deadline, uses that deadline as lease
	// `ExpireTime`.
	LeaseDuration time.Duration
	// ConfigGroups are the ConfigGroups that are watching this CL.
	//
	// They are used to remove votes for additional modes. Normally, there is
	// just 1 ConfigGroup.
	ConfigGroups []*prjcfg.ConfigGroup
	// RunCLExternalIDs are IDs of all CLs involved in the Run.
	//
	// It will be included in `botdata.BotData` and posted to Gerrit as part of
	// the message in "unhappy path". See doc for `Cancel()`
	//
	// TODO(yiwzhang): consider dropping after M1 is launched if it is not adding
	// any value to include those IDs in the bot data.
	RunCLExternalIDs []changelist.ExternalID
}

Input contains info to cancel triggers of Run on a CL.

type Notify

type Notify int32

Notify defines whom to notify for the cancellation.

Note: REVIEWERS or VOTERS must be used together with OWNERS. TODO(yiwzhang): Remove this restriction if necessary.

const (
	// NONE notifies no one.
	NONE Notify = 0
	// OWNER notifies the owner of the CL.
	OWNER Notify = 1
	// REVIEWERS notifies all reviewers of the CL.
	REVIEWERS Notify = 2
	// VOTERS notifies all users that have voted on CQ label when cancelling.
	VOTERS Notify = 4
)