blob: 4f31aaf334d6ad008c210bad7b2970cf75560f40 [file] [log] [blame]
Copybara854996b2021-09-07 19:36:02 +00001// Copyright 2020 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file or at
4// https://developers.google.com/open-source/licenses/bsd
5
6// This file defines protobufs for issues and related business
7// objects, e.g., field values, comments, and attachments.
8
9syntax = "proto3";
10
11package monorail.v3;
12
Adrià Vilanova Martínezac4a6442022-05-15 19:05:13 +020013option go_package = "infra/monorailv2/api/v3/api_proto";
Copybara854996b2021-09-07 19:36:02 +000014
15import "google/api/field_behavior.proto";
16import "google/api/resource.proto";
17import "google/protobuf/timestamp.proto";
18
19// Represents a comment and any associated changes to an Issue.
20//
21// Comments cannot be Created or Updated through standard methods. The
22// OUTPUT_ONLY annotations here indicate fields that would never be provided
23// by the user even if these methods were made available.
24// Next available tag: 11.
25message Comment {
26
27 // The type of comment.
28 // Next available tag: 9
29 enum Type {
30 // The default comment type. Used if type is omitted.
31 UNSPECIFIED = 0;
32 // A standard comment on an issue.
33 COMMENT = 1;
34 // A comment representing a new description for the issue.
35 DESCRIPTION = 2;
36 }
37
38 // A file attached to a comment.
39 // Next available tag: 8
40 message Attachment {
41 // The name of the attached file.
42 string filename = 1;
43 // It is possible for attachments to be deleted (and undeleted) by the
44 // uploader. The name of deleted attachments are still shown, but the
45 // content is not available.
46 IssueContentState state = 2;
47 // Size of the attached file in bytes.
48 uint64 size = 3;
49 // The type of content contained in the file, using the IANA's media type
50 // https://www.iana.org/assignments/media-types/media-types.xhtml.
51 string media_type = 4;
52 // The URI used for a preview of the attachment (when relelvant).
53 string thumbnail_uri = 5;
54 // The URI used to view the content of the attachment.
55 string view_uri = 6;
56 // The URI used to download the content of the attachment.
57 string download_uri = 7;
58 }
59
60 // This message is only suitable for displaying the amendment to users.
61 // We don't currently offer structured amendments that client code can
62 // reason about, field names can be ambiguous, and we don't have
63 // old_value for most changes.
64 // Next available tag: 4
65 message Amendment {
66 // This may be the name of a built-in or custom field, or relative to
67 // an approval field name.
68 string field_name = 1;
69 // This may be a new value that overwrote the old value, e.g., "Assigned",
70 // or it may be a space-separated list of changes, e.g., "Size-L -Size-S".
71 string new_or_delta_value = 2;
72 // old_value is only used when the user changes the summary.
73 string old_value = 3;
74 }
75
76 option (google.api.resource) = {
77 type: "api.crbug.com/Comment"
78 pattern: "projects/{project}/issues/{issue}/comments/{comment}"
79 };
80
81 // Resource name of the comment.
82 string name = 1;
83 // The state of the comment.
84 IssueContentState state = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
85 // The type of comment.
86 Type type = 3;
87 // The text of the comment.
88 string content = 4;
89 // Resource name of the author of the comment.
90 string commenter = 5 [
91 (google.api.resource_reference) = { type: "api.crbug.com/User" },
92 (google.api.field_behavior) = OUTPUT_ONLY
93 ];
94 // The time this comment was added to the Issue.
95 google.protobuf.Timestamp create_time = 6
96 [(google.api.field_behavior) = OUTPUT_ONLY];
97 // Optional string full text of an email that caused this comment to be added.
98 string inbound_message = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
99 // The approval this comment is associated with, if applicable.
100 string approval = 8
101 [(google.api.resource_reference) = { type: "api.crbug.com/ApprovalValue" }];
102 // Any changes made to the issue in association with this comment.
103 repeated Amendment amendments = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
104 // Any attachments uploaded in association with this comment.
105 repeated Attachment attachments = 10
106 [(google.api.field_behavior) = OUTPUT_ONLY];
107}
108
109
110// Many values on an issue can be set either explicitly or by a rule.
111//
112// Note: Though Derivations are used as OUTPUT_ONLY, values including them
113// will still be ingested even though the Derivation is ignored.
114//
115// Next available tag: 3
116enum Derivation {
117 // The default derivation. This value is used if the derivation is omitted.
118 DERIVATION_UNSPECIFIED = 0;
119 // The value was explicitly set on the issue.
120 EXPLICIT = 1;
121 // Value was auto-applied to the issue based on a project's rule. See
122 // monorail/doc/userguide/project-owners.md#how-to-configure-filter-rules
123 RULE = 2;
124}
125
126
127// A value of a custom field for an issue.
128// Next available tag: 5
129message FieldValue {
130 // The project-defined field associated with this value
131 string field = 1 [
132 (google.api.resource_reference) = { type: "api.crbug.com/FieldDef" }];
133 // The value associated with the field.
134 // Mapping of field types to string value:
135 // ENUM_TYPE(int) => str(value)
136 // INT_TYPE(int) => str(value)
137 // STR_TYPE(str) => value
138 // USER_TYPE(int) => the user's resource name
139 // DATE_TYPE(int) => str(int) representing time in seconds since epoch
140 // URL_TYPE(str) => value
141 string value = 2;
142 // How the value was derived.
143 Derivation derivation = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
144 // Issues with phase-specific fields can have values for each phase.
145 string phase = 4;
146}
147
148// Documents and tracks a bug, task, or feature request within a Project.
149// Next available tag: 23
150message Issue {
151 option (google.api.resource) = {
152 type: "api.crbug.com/Issue"
153 pattern: "projects/{project}/issues/{issue}"
154 };
155
156 // A possibly rule-derived component for the issue.
157 // Next available tag: 3
158 message ComponentValue {
159 // The component.
160 string component = 1 [
161 (google.api.resource_reference) = { type: "api.crbug.com/ComponentDef" }
162 ];
163 // How the component was derived.
164 Derivation derivation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
165 }
166
167 // A possibly rule-derived label for an issue.
168 // Next available tag: 3
169 message LabelValue {
170 // The label.
171 string label = 1;
172 // How the label was derived.
173 Derivation derivation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
174 }
175
176 // A possibly rule-derived status for an issue.
177 // Next available tag: 3
178 message StatusValue {
179 // The status of the issue. Note that in rare cases this can be a
180 // value not defined in the project's StatusDefs (e.g. if the issue
181 // was moved from another project).
182 string status = 1;
183 // How the status was derived.
184 Derivation derivation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
185 }
186
187 // A possibly rule-derived user value on an issue.
188 // Next available tag: 3
189 message UserValue {
190 // The user.
191 string user = 1
192 [(google.api.resource_reference) = { type: "api.crbug.com/User" }];
193 // How the user value was derived.
194 Derivation derivation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
195 }
196
197 // Resource name of the issue.
198 string name = 1;
199 // A brief summary of the issue. Generally displayed as a user-facing title.
200 // TODO(monorail:6988): The UI limits summary length while the backend does
201 // not. Resolve this discrepancy.
202 string summary = 2;
203 // The state of the issue.
204 IssueContentState state = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
205 // The current status of the issue.
206 StatusValue status = 4 [(google.api.field_behavior) = REQUIRED];
207 // The user who created the issue.
208 string reporter = 5 [
209 (google.api.resource_reference) = { type: "api.crbug.com/User" },
210 (google.api.field_behavior) = OUTPUT_ONLY
211 ];
212 // The user currently responsible for the issue. This user must be a member of
213 // the Project.
214 UserValue owner = 6;
215 // Additional users receiving notifications on the issue.
216 repeated UserValue cc_users = 7;
217 // Labels applied to the issue.
218 repeated LabelValue labels = 8;
219 // Components the issue is associated with.
220 repeated ComponentValue components = 9;
221 // Values for custom fields on the issue.
222 repeated FieldValue field_values = 10;
223 // An issue can be merged into another. If this value is set, the issue
224 // referred to should be considered the primary source for further updates.
225 IssueRef merged_into_issue_ref = 11;
226 // Issues preventing the completion of this issue.
227 repeated IssueRef blocked_on_issue_refs = 12;
228 // Issues for which this issue is blocking completion.
229 repeated IssueRef blocking_issue_refs = 13;
230 // The time the issue was reported.
231 google.protobuf.Timestamp create_time = 14
232 [(google.api.field_behavior) = OUTPUT_ONLY];
233 // The most recent time the issue was closed.
234 google.protobuf.Timestamp close_time = 15
235 [(google.api.field_behavior) = OUTPUT_ONLY];
236 // The most recent time the issue was modified.
237 google.protobuf.Timestamp modify_time = 16
238 [(google.api.field_behavior) = OUTPUT_ONLY];
239 // The most recent time a component value was modified.
240 google.protobuf.Timestamp component_modify_time = 17
241 [(google.api.field_behavior) = OUTPUT_ONLY];
242 // The most recent time the status value was modified.
243 google.protobuf.Timestamp status_modify_time = 18
244 [(google.api.field_behavior) = OUTPUT_ONLY];
245 // The most recent time the owner made a modification to the issue.
246 google.protobuf.Timestamp owner_modify_time = 19
247 [(google.api.field_behavior) = OUTPUT_ONLY];
248 // The number of attachments associated with the issue.
249 uint32 attachment_count = 20 [(google.api.field_behavior) = OUTPUT_ONLY];
250 // The number of users who have starred the issue.
251 uint32 star_count = 21 [(google.api.field_behavior) = OUTPUT_ONLY];
252 // Phases of a process the issue is tracking (if applicable).
253 // See monorail/doc/userguide/concepts.md#issue-approvals-and-gates
254 repeated string phases = 22 [
255 (google.api.field_behavior) = OUTPUT_ONLY];
256}
257
258// States that an issue or its comments can be in (aip.dev/216).
259// Next available tag: 4
260enum IssueContentState {
261 // The default value. This value is used if the state is omitted.
262 STATE_UNSPECIFIED = 0;
263 // The Issue or Comment is available.
264 ACTIVE = 1;
265 // The Issue or Comment has been deleted.
266 DELETED = 2;
267 // The Issue or Comment has been flagged as spam.
268 // Takes precedent over DELETED.
269 SPAM = 3;
270}
271
272// Specifies a column in an issues list view.
273// Next available tag: 2
274message IssuesListColumn {
275 // Column name shown in the column header.
276 string column = 1;
277}
278
279// Refers to an issue that may or may not be tracked in Monorail.
280// At least one of `issue` and `ext_identifier` MUST be set; they MUST NOT both
281// be set.
282// Next available tag: 3
283message IssueRef {
284 // Resource name of an issue tracked in Monorail
285 string issue = 1
286 [(google.api.resource_reference) = { type: "api.crbug.com/Issue" }];
287 // For referencing external issues, e.g. b/1234, or a dangling reference
288 // to an old 'codesite' issue.
289 // TODO(monorail:7208): add more documentation on dangling references.
290 string ext_identifier = 2;
291}
292
293// Documents and tracks an approval process.
294// See monorail/doc/userguide/concepts.md#issue-approvals-and-gates
295// Next available tag: 9
296message ApprovalValue {
297 option (google.api.resource) = {
298 type: "api.crbug.com/ApprovalValue"
299 pattern: "projects/{project}/issues/{issue}/approvalValues/{approval}"
300 };
301
302 // Potential states for an approval. Note that these statuses cause different
303 // sets of notifications. See monorail/doc/userguide/email.md
304 // Next available tag: 9
305 enum ApprovalStatus {
306 // The default approval status. This value is used if the status is omitted.
307 APPROVAL_STATUS_UNSPECIFIED = 0;
308 // No status has yet been set on this value.
309 NOT_SET = 1;
310 // This issue needs review from the approvers for this phase.
311 NEEDS_REVIEW = 2;
312 // This approval is not needed for this issue for this phase.
313 NA = 3;
314 // The issue is ready for the approvers to review.
315 REVIEW_REQUESTED = 4;
316 // The approvers have started reviewing this issue.
317 REVIEW_STARTED = 5;
318 // The approvers need more information.
319 NEED_INFO = 6;
320 // The approvers have approved this issue for this phase.
321 APPROVED = 7;
322 // The approvers have indicated this issue is not approved for this phase.
323 NOT_APPROVED = 8;
324 }
325
326 // The resource name.
327 string name = 1;
328 // The resource name of the ApprovalDef.
329 string approval_def = 2 [
330 (google.api.resource_reference) = { type: "api.crbug.com/ApprovalDef" },
331 (google.api.field_behavior) = OUTPUT_ONLY];
332 // The users able to grant this approval.
333 repeated string approvers = 3 [
334 (google.api.resource_reference) = { type: "api.crbug.com/User" }];
335 // The current status of the approval.
336 ApprovalStatus status = 4;
337 // The time `status` was last set.
338 google.protobuf.Timestamp set_time = 5 [
339 (google.api.field_behavior) = OUTPUT_ONLY];
340 // The user who most recently set `status`.
341 string setter = 6 [
342 (google.api.resource_reference) = { type: "api.crbug.com/User" },
343 (google.api.field_behavior) = OUTPUT_ONLY];
344 // The phase the approval is associated with (if applicable).
345 string phase = 7 [
346 (google.api.field_behavior) = OUTPUT_ONLY];
347 // FieldValues with `approval_def` as their parent.
348 repeated FieldValue field_values = 8;
349}