Project import generated by Copybara.
GitOrigin-RevId: d9e9e3fb4e31372ec1fb43b178994ca78fa8fe70
diff --git a/api/v3/api_proto/issue_objects.proto b/api/v3/api_proto/issue_objects.proto
new file mode 100644
index 0000000..2c5cf69
--- /dev/null
+++ b/api/v3/api_proto/issue_objects.proto
@@ -0,0 +1,349 @@
+// 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;
+}
\ No newline at end of file