Documentation

Overview

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

    Index

    Constants

    This section is empty.

    Variables

    View Source
    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).

      View Source
      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, in Input) error

          Cancel removes all votes on CQ label and posts the given message.

          If the patcheset of the passed CL is not current, returns error tagged with `ErrPreconditionFailedTag`.

          The triggering votes will be removed last and all other votes will be removed in chronological order (latest to earliest). Message will posted in the same rpc call to Gerrit that removes the triggering votes.

          Returns nil if all votes are successfully removed or no action was even necessary.

          If non-recoverable error occurs(e.g. lack of permission to remove votes), attempts to post the message including original message in the input, failure message and special `botdata.BotData` s.t. user is clearly communicated with the error and CV won't create new Run by parsing the `BotData` message. The returned error will be tagged with `ErrPermanentTag`.

          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
          	// 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
              )

              Source Files