// Copyright 2020 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file or at
// https://developers.google.com/open-source/licenses/bsd

// This file defines protobufs for issues and related business
// objects, e.g., field values, comments, and attachments.

syntax = "proto3";

package monorail.v3;

option go_package = "api/v3/api_proto";

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/timestamp.proto";

// Represents a comment and any associated changes to an Issue.
//
// Comments cannot be Created or Updated through standard methods. The
// OUTPUT_ONLY annotations here indicate fields that would never be provided
// by the user even if these methods were made available.
// Next available tag: 11.
message Comment {

  // The type of comment.
  // Next available tag: 9
  enum Type {
    // The default comment type. Used if type is omitted.
    UNSPECIFIED = 0;
    // A standard comment on an issue.
    COMMENT = 1;
    // A comment representing a new description for the issue.
    DESCRIPTION = 2;
  }

  // A file attached to a comment.
  // Next available tag: 8
  message Attachment {
    // The name of the attached file.
    string filename = 1;
    // It is possible for attachments to be deleted (and undeleted) by the
    // uploader. The name of deleted attachments are still shown, but the
    // content is not available.
    IssueContentState state = 2;
    // Size of the attached file in bytes.
    uint64 size = 3;
    // The type of content contained in the file, using the IANA's media type
    // https://www.iana.org/assignments/media-types/media-types.xhtml.
    string media_type = 4;
    // The URI used for a preview of the attachment (when relelvant).
    string thumbnail_uri = 5;
    // The URI used to view the content of the attachment.
    string view_uri = 6;
    // The URI used to download the content of the attachment.
    string download_uri = 7;
  }

  // This message is only suitable for displaying the amendment to users.
  // We don't currently offer structured amendments that client code can
  // reason about, field names can be ambiguous, and we don't have
  // old_value for most changes.
  // Next available tag: 4
  message Amendment {
    // This may be the name of a built-in or custom field, or relative to
    // an approval field name.
    string field_name = 1;
    // This may be a new value that overwrote the old value, e.g., "Assigned",
    // or it may be a space-separated list of changes, e.g., "Size-L -Size-S".
    string new_or_delta_value = 2;
    // old_value is only used when the user changes the summary.
    string old_value = 3;
  }

  option (google.api.resource) = {
    type: "api.crbug.com/Comment"
    pattern: "projects/{project}/issues/{issue}/comments/{comment}"
  };

  // Resource name of the comment.
  string name = 1;
  // The state of the comment.
  IssueContentState state = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The type of comment.
  Type type = 3;
  // The text of the comment.
  string content = 4;
  // Resource name of the author of the comment.
  string commenter = 5 [
    (google.api.resource_reference) = { type: "api.crbug.com/User" },
    (google.api.field_behavior) = OUTPUT_ONLY
  ];
  // The time this comment was added to the Issue.
  google.protobuf.Timestamp create_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];
  // Optional string full text of an email that caused this comment to be added.
  string inbound_message = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The approval this comment is associated with, if applicable.
  string approval = 8
      [(google.api.resource_reference) = { type: "api.crbug.com/ApprovalValue" }];
  // Any changes made to the issue in association with this comment.
  repeated Amendment amendments = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Any attachments uploaded in association with this comment.
  repeated Attachment attachments = 10
      [(google.api.field_behavior) = OUTPUT_ONLY];
}


// Many values on an issue can be set either explicitly or by a rule.
//
// Note: Though Derivations are used as OUTPUT_ONLY, values including them
// will still be ingested even though the Derivation is ignored.
//
// Next available tag: 3
enum Derivation {
  // The default derivation. This value is used if the derivation is omitted.
  DERIVATION_UNSPECIFIED = 0;
  // The value was explicitly set on the issue.
  EXPLICIT = 1;
  // Value was auto-applied to the issue based on a project's rule. See
  // monorail/doc/userguide/project-owners.md#how-to-configure-filter-rules
  RULE = 2;
}


// A value of a custom field for an issue.
// Next available tag: 5
message FieldValue {
  // The project-defined field associated with this value
  string field = 1 [
      (google.api.resource_reference) = { type: "api.crbug.com/FieldDef" }];
  // The value associated with the field.
  // Mapping of field types to string value:
  // ENUM_TYPE(int) => str(value)
  // INT_TYPE(int) => str(value)
  // STR_TYPE(str) => value
  // USER_TYPE(int) => the user's resource name
  // DATE_TYPE(int) => str(int) representing time in seconds since epoch
  // URL_TYPE(str) => value
  string value = 2;
  // How the value was derived.
  Derivation derivation = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Issues with phase-specific fields can have values for each phase.
  string phase = 4;
}

// Documents and tracks a bug, task, or feature request within a Project.
// Next available tag: 23
message Issue {
  option (google.api.resource) = {
    type: "api.crbug.com/Issue"
    pattern: "projects/{project}/issues/{issue}"
  };

  // A possibly rule-derived component for the issue.
  // Next available tag: 3
  message ComponentValue {
    // The component.
    string component = 1 [
      (google.api.resource_reference) = { type: "api.crbug.com/ComponentDef" }
    ];
    // How the component was derived.
    Derivation derivation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // A possibly rule-derived label for an issue.
  // Next available tag: 3
  message LabelValue {
    // The label.
    string label = 1;
    // How the label was derived.
    Derivation derivation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // A possibly rule-derived status for an issue.
  // Next available tag: 3
  message StatusValue {
    // The status of the issue. Note that in rare cases this can be a
    // value not defined in the project's StatusDefs (e.g. if the issue
    // was moved from another project).
    string status = 1;
    // How the status was derived.
    Derivation derivation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // A possibly rule-derived user value on an issue.
  // Next available tag: 3
  message UserValue {
    // The user.
    string user = 1
        [(google.api.resource_reference) = { type: "api.crbug.com/User" }];
    // How the user value was derived.
    Derivation derivation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Resource name of the issue.
  string name = 1;
  // A brief summary of the issue. Generally displayed as a user-facing title.
  // TODO(monorail:6988): The UI limits summary length while the backend does
  // not. Resolve this discrepancy.
  string summary = 2;
  // The state of the issue.
  IssueContentState state = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The current status of the issue.
  StatusValue status = 4 [(google.api.field_behavior) = REQUIRED];
  // The user who created the issue.
  string reporter = 5 [
    (google.api.resource_reference) = { type: "api.crbug.com/User" },
    (google.api.field_behavior) = OUTPUT_ONLY
  ];
  // The user currently responsible for the issue. This user must be a member of
  // the Project.
  UserValue owner = 6;
  // Additional users receiving notifications on the issue.
  repeated UserValue cc_users = 7;
  // Labels applied to the issue.
  repeated LabelValue labels = 8;
  // Components the issue is associated with.
  repeated ComponentValue components = 9;
  // Values for custom fields on the issue.
  repeated FieldValue field_values = 10;
  // An issue can be merged into another. If this value is set, the issue
  // referred to should be considered the primary source for further updates.
  IssueRef merged_into_issue_ref = 11;
  // Issues preventing the completion of this issue.
  repeated IssueRef blocked_on_issue_refs = 12;
  // Issues for which this issue is blocking completion.
  repeated IssueRef blocking_issue_refs = 13;
  // The time the issue was reported.
  google.protobuf.Timestamp create_time = 14
      [(google.api.field_behavior) = OUTPUT_ONLY];
  // The most recent time the issue was closed.
  google.protobuf.Timestamp close_time = 15
      [(google.api.field_behavior) = OUTPUT_ONLY];
  // The most recent time the issue was modified.
  google.protobuf.Timestamp modify_time = 16
      [(google.api.field_behavior) = OUTPUT_ONLY];
  // The most recent time a component value was modified.
  google.protobuf.Timestamp component_modify_time = 17
      [(google.api.field_behavior) = OUTPUT_ONLY];
  // The most recent time the status value was modified.
  google.protobuf.Timestamp status_modify_time = 18
      [(google.api.field_behavior) = OUTPUT_ONLY];
  // The most recent time the owner made a modification to the issue.
  google.protobuf.Timestamp owner_modify_time = 19
      [(google.api.field_behavior) = OUTPUT_ONLY];
  // The number of attachments associated with the issue.
  uint32 attachment_count = 20 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The number of users who have starred the issue.
  uint32 star_count = 21 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Phases of a process the issue is tracking (if applicable).
  // See monorail/doc/userguide/concepts.md#issue-approvals-and-gates
  repeated string phases = 22 [
      (google.api.field_behavior) = OUTPUT_ONLY];
}

// States that an issue or its comments can be in (aip.dev/216).
// Next available tag: 4
enum IssueContentState {
  // The default value. This value is used if the state is omitted.
  STATE_UNSPECIFIED = 0;
  // The Issue or Comment is available.
  ACTIVE = 1;
  // The Issue or Comment has been deleted.
  DELETED = 2;
  // The Issue or Comment has been flagged as spam.
  // Takes precedent over DELETED.
  SPAM = 3;
}

// Specifies a column in an issues list view.
// Next available tag: 2
message IssuesListColumn {
  // Column name shown in the column header.
  string column = 1;
}

// Refers to an issue that may or may not be tracked in Monorail.
// At least one of `issue` and `ext_identifier` MUST be set; they MUST NOT both
// be set.
// Next available tag: 3
message IssueRef {
  // Resource name of an issue tracked in Monorail
  string issue = 1
      [(google.api.resource_reference) = { type: "api.crbug.com/Issue" }];
  // For referencing external issues, e.g. b/1234, or a dangling reference
  // to an old 'codesite' issue.
  // TODO(monorail:7208): add more documentation on dangling references.
  string ext_identifier = 2;
}

// Documents and tracks an approval process.
// See monorail/doc/userguide/concepts.md#issue-approvals-and-gates
// Next available tag: 9
message ApprovalValue {
  option (google.api.resource) = {
     type: "api.crbug.com/ApprovalValue"
     pattern: "projects/{project}/issues/{issue}/approvalValues/{approval}"
   };

  // Potential states for an approval. Note that these statuses cause different
  // sets of notifications. See monorail/doc/userguide/email.md
  // Next available tag: 9
  enum ApprovalStatus {
    // The default approval status. This value is used if the status is omitted.
    APPROVAL_STATUS_UNSPECIFIED = 0;
    // No status has yet been set on this value.
    NOT_SET = 1;
    // This issue needs review from the approvers for this phase.
    NEEDS_REVIEW = 2;
    // This approval is not needed for this issue for this phase.
    NA = 3;
    // The issue is ready for the approvers to review.
    REVIEW_REQUESTED = 4;
    // The approvers have started reviewing this issue.
    REVIEW_STARTED = 5;
    // The approvers need more information.
    NEED_INFO = 6;
    // The approvers have approved this issue for this phase.
    APPROVED = 7;
    // The approvers have indicated this issue is not approved for this phase.
    NOT_APPROVED = 8;
  }

  // The resource name.
  string name = 1;
  // The resource name of the ApprovalDef.
  string approval_def = 2 [
      (google.api.resource_reference) = { type: "api.crbug.com/ApprovalDef" },
      (google.api.field_behavior) = OUTPUT_ONLY];
  // The users able to grant this approval.
  repeated string approvers = 3 [
      (google.api.resource_reference) = { type: "api.crbug.com/User" }];
  // The current status of the approval.
  ApprovalStatus status = 4;
  // The time `status` was last set.
  google.protobuf.Timestamp set_time = 5 [
      (google.api.field_behavior) = OUTPUT_ONLY];
  // The user who most recently set `status`.
  string setter = 6 [
      (google.api.resource_reference) = { type: "api.crbug.com/User" },
      (google.api.field_behavior) = OUTPUT_ONLY];
  // The phase the approval is associated with (if applicable).
  string phase = 7 [
      (google.api.field_behavior) = OUTPUT_ONLY];
  // FieldValues with `approval_def` as their parent.
  repeated FieldValue field_values = 8;
}