cv/api/v0/tryjob.proto

// Copyright 2021 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package cv.v0;

option go_package = "go.chromium.org/luci/cv/api/v0;cvpb";

// Tryjob represents a Run's view of a Tryjob.
message Tryjob {
  // Status is a high level status of a Tryjob.
  enum Status {
    // STATUS_UNSPECIFIED is never used.
    STATUS_UNSPECIFIED = 0;

    // PENDING means Tryjob is being triggered by CV.
    //
    // *must* have no Result.
    PENDING = 1;
    // TRIGGERED means Tryjob was triggered.
    //
    // *may* have been triggered by not CV but another user, service, etc.
    // *may* have a Result, which *may* still change.
    TRIGGERED = 2;
    // ENDED is a completed Tryjob. Final status.
    //
    // *must* have a Result, whose Status is not UNKNOWN.
    ENDED = 3;
    // CANCELLED is Tryjob cancelled by CV. Final status.
    //
    // *must* have no Result.
    CANCELLED = 4;
    // UNTRIGGERED means Tryjob was not triggered. Final status.
    //
    // *must* have no Result.
    UNTRIGGERED = 5;
  }

  // Result of a Tryjob.
  message Result {
    // Status of the Result.
    //
    // This is the verdict of verification of Run's CLs by this Tryjob.
    Status status = 1;

    enum Status {
      // RESULT_STATUS_UNSPECIFIED is never used.
      RESULT_STATUS_UNSPECIFIED = 0;
      // UNKNOWN means Tryjob didn't reach a conclusion.
      UNKNOWN = 1;
      // SUCCEEDED means that Run's CLs are considered OK by this Tryjob.
      SUCCEEDED = 2;
      // FAILED_PERMANENTLY means that Run's CLs are most likely not good.
      FAILED_PERMANENTLY = 3;
      // FAILED_TRANSIENTLY means that Run's CLs are most likely not to blame
      // for the failure.
      // TODO(crbug/1227363): consider removing transiency aspect if possible.
      FAILED_TRANSIENTLY = 4;
      // TIMEOUT means the Tryjob ran over some deadline and did not make a
      // decision about this Run's CLs.
      TIMEOUT = 5;
    }

    // Backend houses backend-specific output.
    oneof backend {
      Buildbucket buildbucket = 5;
    }

    message Buildbucket {
      int64 id = 1;
      reserved 2; // status
    }
  }

  reserved 1; // definition

  // Status of the Tryjob.
  Status status = 2;

  // Result of the Tryjob.
  Result result = 3;

  // Indicates whether this Tryjob is considered critical to a Run's final
  // status. If true, failure of this Tryjob will fail the Run immediately.
  // Run is considered SUCCEEDED iff all critical Tryjobs have passed.
  //
  // As of Mar. 2022, a Tryjob is considered critical if it is not experimental
  // or it is triggered directly by `Cq-Include-Trybots` footer.
  bool critical = 4;

  // Indicates whether a Run is reusing this Tryjob rather than triggering
  // its own Tryjob. A Run may reuse Tryjobs triggered by some previous Runs or
  // maually by users as long as CV sees fit.
  bool reuse = 5;
}