blob: 4f31aaf334d6ad008c210bad7b2970cf75560f40 [file] [log] [blame]
// 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 = "infra/monorailv2/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;
}