blob: 988f958717365d031549b32a654cba6b75e75e43 [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
6syntax = "proto3";
7
8package monorail.v3;
9
10option go_package = "api/v3/api_proto";
11
12import "google/protobuf/field_mask.proto";
13import "google/api/field_behavior.proto";
14import "google/api/resource.proto";
15import "api/v3/api_proto/issue_objects.proto";
16
17// ***ONLY CALL rpcs WITH `status: {ALPHA|STABLE}`***
18// rpcs without `status` are not ready.
19
20// Issues service includes all methods needed for managing Issues.
21service Issues {
22 // status: ALPHA
23 // Returns the requested Issue.
24 //
25 // Raises:
26 // INVALID_ARGUMENT if `name` is formatted incorrectly.
27 // NOT_FOUND if the issue does not exist.
28 // PERMISSION_DENIED if the requester is not allowed to view the issue.
29 rpc GetIssue (GetIssueRequest) returns (Issue) {}
30
31 // status: ALPHA
32 // Returns the requested Issues.
33 //
34 // Raises:
35 // INVALID_ARGUMENT if `names` is formatted incorrectly. Or if a parent
36 // collection in `names` does not match the value in `parent`.
37 // NOT_FOUND if any of the given issues do not exist.
38 // PERMISSION_DENIED if the requester does not have permission to view one
39 // (or more) of the given issues.
40 rpc BatchGetIssues(BatchGetIssuesRequest) returns (BatchGetIssuesResponse) {}
41
42 // status: ALPHA
43 // Searches over issues within the specified projects.
44 //
45 // Raises:
46 // INVALID_ARGUMENT if project names or search query are invalid.
47 rpc SearchIssues (SearchIssuesRequest) returns (SearchIssuesResponse) {}
48
49 // status: ALPHA
50 // Lists comments for an issue.
51 //
52 // Raises:
53 // INVALID_ARGUMENT if `parent` is formatted incorrectly or `page_size` < 0.
54 // NOT_FOUND if `parent` does not exist.
55 // PERMISSION_DENIED if the requester is not allowed to view `parent`.
56 rpc ListComments (ListCommentsRequest) returns (ListCommentsResponse) {}
57
58 // status: ALPHA
59 // Modifies Issues and creates a new Comment for each.
60 // Issues with NOOP changes and no comment_content will not be updated
61 // and will not be included in the response.
62 // We do not offer a standard UpdateIssue because every issue change
63 // must result in the side-effect of creating a new Comment, and may result in
64 // the side effect of sending a notification. We also want to allow for any
65 // combination of issue changes to be made at once in a monolithic method.
66 //
67 // Raises:
68 // INVALID_ARGUMENT required fields are missing or fields are formatted
69 // incorrectly.
70 // NOT_FOUND if any specified issues are not found.
71 // PERMISSION_DENIED if the requester is not allowed to make the
72 // requested change.
73 rpc ModifyIssues (ModifyIssuesRequest) returns (ModifyIssuesResponse) {}
74
75 // status: ALPHA
76 // Modifies ApprovalValues and creates a new Comment for each delta.
77 // We do not offer a standard UpdateApprovalValue because changes result
78 // in creating Comments on the parent Issue, and may have the side effect of
79 // sending notifications. We also want to allow for any combination of
80 // approval changes to be made at once in a monolithic method.
81 // To modify owner add 'owner' to update_mask, though 'owner.user' works too.
82 //
83 // Raises:
84 // INVALID_ARGUMENT required fields are missing or fields are formatted
85 // incorrectly.
86 // NOT_FOUND if any specified ApprovalValues are not found.
87 // PERMISSION_DENIED if the requester is not allowed to make any of the
88 // requested changes.
89 rpc ModifyIssueApprovalValues (ModifyIssueApprovalValuesRequest) returns
90 (ModifyIssueApprovalValuesResponse) {}
91
92 // status: ALPHA
93 // Lists approval values for an issue.
94 //
95 // Raises:
96 // INVALID_ARGUMENT if request `parent` is formatted incorrectly.
97 // NOT_FOUND if the parent issue does not exist.
98 // PERMISSION_DENIED if the requester is not allowed to view parent issue.
99 rpc ListApprovalValues (ListApprovalValuesRequest) returns
100 (ListApprovalValuesResponse) {}
101
102 // status: NOT READY
103 // Changes state for a comment. Supported state transitions:
104 // - ACTIVE -> DELETED
105 // - ACTIVE -> SPAM
106 // - DELETED -> ACTIVE
107 // - SPAM -> ACTIVE
108 //
109 // Raises:
110 // TODO(crbug/monorail/7867): Document errors when implemented
111 rpc ModifyCommentState (ModifyCommentStateRequest) returns
112 (ModifyCommentStateResponse) {}
113
114 // status: NOT READY
115 // Makes an issue from an IssueTemplate and deltas.
116 //
117 // Raises:
118 // TODO(crbug/monorail/7197): Document errors when implemented
119 rpc MakeIssueFromTemplate (MakeIssueFromTemplateRequest) returns (Issue) {}
120
121 // status: ALPHA
122 // Makes a basic issue, does not support phases, approvals, or approval
123 // fields.
124 // We do not offer a standard CreateIssue because Issue descriptions are
125 // required, but not included in the Issue proto.
126 //
127 // Raises:
128 // INVALID_ARGUMENT if any given names does not have a valid format, if any
129 // fields in the requested issue were invalid, or if proposed values
130 // violates filter rules that should error.
131 // NOT_FOUND if no project exists with the given name.
132 // PERMISSION_DENIED if user lacks sufficient permissions.
133 rpc MakeIssue (MakeIssueRequest) returns (Issue) {}
134}
135
136
137// The request message for Issues.GetIssue.
138// Next available tag: 2
139message GetIssueRequest {
140 // The name of the issue to request.
141 string name = 1 [
142 (google.api.resource_reference) = {type: "api.crbug.com/Issue"},
143 (google.api.field_behavior) = REQUIRED ];
144}
145
146// The request message for Issues.BatchGetIssues.
147// Next available tag: 3
148message BatchGetIssuesRequest {
149 // The project name from which to batch get issues. If included, the parent
150 // of all the issues specified in `names` must match this field.
151 string parent = 1 [
152 (google.api.resource_reference) = {type: "api.crbug.com/Project"} ];
153 // The issues to request. Maximum of 100 can be retrieved.
154 repeated string names = 2 [
155 (google.api.resource_reference) = {type: "api.crbug.com/Issue"} ];
156}
157
158// The response message for Issues.BatchGetIssues.
159// Next available tag: 2
160message BatchGetIssuesResponse {
161 // Issues matching the given request.
162 repeated Issue issues = 1;
163}
164
165// The request message for Issues.SearchIssues.
166// Next available tag: 6
167message SearchIssuesRequest {
168 // The names of Projects in which to search issues.
169 repeated string projects = 1 [
170 (google.api.resource_reference) = {type: "api.crbug.com/Project"},
171 (google.api.field_behavior) = REQUIRED ];
172 // The query string can contain any number of free text and
173 // field search expressions.
174 // Please see https://bugs.chromium.org/p/chromium/issues/searchtips for more
175 // details of how the query string works.
176 //
177 // Canned queries have been deprecated in v3 in favor of search scoping using
178 // parentheses support.
179 // For clients who previously used canned queries, we're providing the
180 // mapping of legacy canned query IDs to Monorail search syntax:
181 // - Format: (can_id, description, query_string)
182 // - (1, 'All issues', '')
183 // - (2, 'Open issues', 'is:open')
184 // - (3, 'Open and owned by me', 'is:open owner:me')
185 // - (4, 'Open and reported by me', 'is:open reporter:me')
186 // - (5, 'Open and starred by me', 'is:open is:starred')
187 // - (6, 'New issues', 'status:new')
188 // - (7, 'Issues to verify', 'status=fixed,done')
189 // - (8, 'Open with comment by me', 'is:open commentby:me')
190 string query = 2;
191 // The maximum number of items to return. The service may return fewer than
192 // this value.
193 // If unspecified, at most 100 items will be returned.
194 // The maximum value is 100; values above 100 will be coerced to 100.
195 int32 page_size = 3;
196 // A page token, received from a previous `SearchIssues` call.
197 // Provide this to retrieve the subsequent page.
198 //
199 // When paginating, all other parameters provided to `SearchIssues` must match
200 // the call that provided the page token.
201 string page_token = 4;
202 // The string of comma separated field names used to order the items.
203 // Adding '-' before a field, reverses the sort order.
204 // E.g. 'stars,-status' sorts the items by number of stars, high to low,
205 // then by status, low to high.
206 string order_by = 5;
207}
208
209// The response message for Issues.SearchIssues.
210// Next available tag: 3
211message SearchIssuesResponse {
212 // Issues matching the given request.
213 repeated Issue issues = 1;
214 // A token, which can be sent as `page_token` to retrieve the next page.
215 // If this field is omitted, there are no subsequent pages.
216 string next_page_token = 2;
217}
218
219// The request message for Issues.ListComments.
220// Next available tag: 5
221message ListCommentsRequest {
222 // The name of the issue for which to list comments.
223 string parent = 1 [
224 (google.api.resource_reference) = {type: "api.crbug.com/Issue"},
225 (google.api.field_behavior) = REQUIRED ];
226 // The maximum number of items to return. The service may return fewer than
227 // this value.
228 // If unspecified, at most 100 items will be returned.
229 // The maximum value is 100; values above 100 will be coerced to 100.
230 int32 page_size = 2;
231 // A page token, received from a previous `ListComments` call.
232 // Provide this to retrieve the subsequent page.
233 //
234 // When paginating, all other parameters provided to `ListComments` must
235 // match the call that provided the page token.
236 string page_token = 3;
237 // For our initial release this filter only supports filtering to comments
238 // related to a specific approval.
239 // For example `approval = "projects/monorail/approvalDefs/1"`,
240 // Note that no further logical or comparison operators are supported
241 string filter = 4;
242}
243
244// The response message for Issues.ListComments
245// Next available tag: 3
246message ListCommentsResponse {
247 // The comments from the specified issue.
248 repeated Comment comments = 1;
249 // A token, which can be sent as `page_token` to retrieve the next page.
250 // If this field is omitted, there are no subsequent pages.
251 string next_page_token = 2;
252}
253
254// An attachment to upload to a comment or description.
255// Next available tag: 3
256message AttachmentUpload {
257 string filename = 1 [ (google.api.field_behavior) = REQUIRED ];
258 bytes content = 2 [ (google.api.field_behavior) = REQUIRED ];
259}
260
261// Holds changes to one issue, used in ModifyIssuesRequest.
262// Next available tag: 9
263message IssueDelta {
264 // The issue's `name` field is used to identify the issue to be
265 // updated. `issue.name` must always be filled.
266 //
267 // Values with rule-based Derivation within `issue` and in `field_vals_remove`
268 // will be ignored.
269 Issue issue = 1 [
270 (google.api.field_behavior) = REQUIRED ];
271 // The list of fields in `issue` to be updated.
272 //
273 // Repeated fields set on `issue` will be appended to.
274 //
275 // Non-repeated fields (e.g. `owner`) can be set with `issue.owner` set and
276 // either 'owner' or 'owner.user' added to `update_mask`.
277 // To unset non-repeated fields back to their default value, `issue.owner`
278 // must contain the default value and `update_mask` must include 'owner.user'
279 // NOT 'owner'.
280 //
281 // Its `field_values`, however, are a special case. Fields can be specified as
282 // single-value or multi-value in their FieldDef.
283 //
284 // Single-value Field: if there is preexisting FieldValue with the same
285 // `field` and `phase`, it will be REPLACED.
286 //
287 // Multi-value Field: a new value will be appended, unless the same `field`,
288 // `phase`, `value` combination already exists. In that case, the FieldValue
289 // will be ignored. In other words, duplicate values are ignored.
290 // (With the exception of crbug.com/monorail/8137 until it is fixed).
291 google.protobuf.FieldMask update_mask = 2 [
292 (google.api.field_behavior) = REQUIRED ];
293
294 // Values to remove from the repeated fields of the issue.
295
296 // Cc's to remove.
297 repeated string ccs_remove = 3 [
298 (google.api.resource_reference) = {type: "api.crbug.com/User"}];
299 // Blocked_on issues to remove.
300 repeated IssueRef blocked_on_issues_remove = 4;
301 // Blocking issues to remove.
302 repeated IssueRef blocking_issues_remove = 5;
303 // Components to remove.
304 repeated string components_remove = 6 [
305 (google.api.resource_reference) = {type: "api.crbug.com/ComponentDef"}];
306 // Labels to remove.
307 repeated string labels_remove = 7;
308 // FieldValues to remove. Any values that did not already exist will be
309 // ignored e.g. if you append a FieldValue in issue and remove it here, it
310 // will still be added.
311 repeated FieldValue field_vals_remove = 8;
312
313 // TODO(crbug.com/monorail/8019): add Attachment uploading and removing.
314}
315
316// Changes to make to an ApprovalValue. Used to ModifyIssueApprovalValues or
317// to MakeIssueFromTemplate.
318//
319// NOTE: The same handling of FieldValues discussed in IssueDelta applies here.
320// Next available tag: 6
321message ApprovalDelta {
322 // The ApprovalValue we want to update. `approval_value.name` must always be
323 // set.
324 ApprovalValue approval_value = 1;
325 // Repeated fields found in `update_mask` will be appended to.
326 google.protobuf.FieldMask update_mask = 2 [
327 (google.api.field_behavior) = REQUIRED ];
328 // Resource names of the approvers we want to remove.
329 repeated string approvers_remove = 3 [
330 (google.api.resource_reference) = { type: "api.crbug.com/User" }
331 ];
332 // FieldValues that do not belong to `approval_value` will trigger error.
333 repeated FieldValue field_vals_remove = 5;
334 // TODO(crbug.com/monorail/8019): add Attachment uploading and removing.
335}
336
337
338// The type of notification a change should trigger.
339// See monorail/doc/userguide/email.md
340// Next available tag: 2
341enum NotifyType {
342 // The default value. This value is unused.
343 NOTIFY_TYPE_UNSPECIFIED = 0;
344 // An email notification should be sent.
345 EMAIL = 1;
346 // No notifcation should be triggered at all.
347 NO_NOTIFICATION = 2;
348}
349
350
351// The request message for Issues.ModifyIssues.
352// Next available tag: 5
353message ModifyIssuesRequest {
354 // The issue changes to make. A maximum of 100 issue changes can be requested.
355 // There is also a constraint of 50 additional 'impacted issues' per
356 // ModifyIssuesRequest. 'Impacted issues' are issues that are adding/removing
357 // `blocked_on`, `blocking`, or `merge`
358 // If you encounter this error, consider significantly smaller batches.
359 repeated IssueDelta deltas = 1;
360 // The type of notification the modifications should trigger.
361 NotifyType notify_type = 2;
362 // The comment text that should be added to each issue in delta.
363 // Max length is 51200 characters.
364 string comment_content = 3;
365 // The attachment that will be to each comment for each issue in delta.
366 repeated AttachmentUpload uploads = 4;
367}
368
369
370// The response message for Issues.ModifyIssues.
371// Next available tag: 2
372message ModifyIssuesResponse {
373 // The updated issues.
374 repeated Issue issues = 1;
375}
376
377// The request message for Issues.ModifyIssueApprovalValues.
378// Next available tag: 4
379message ModifyIssueApprovalValuesRequest {
380 // The ApprovalValue changes to make. Maximum of 100 deltas can be requested.
381 repeated ApprovalDelta deltas = 1;
382 // The type of notification the modifications should trigger.
383 NotifyType notify_type = 2;
384 // The `content` of the Comment created for each change in `deltas`.
385 // Max length is 51200 characters.
386 string comment_content = 3;
387}
388
389// The response message for Issues.ModifyIssueApprovalValuesRequest.
390// Next available tag: 2
391message ModifyIssueApprovalValuesResponse {
392 // The updated ApprovalValues.
393 repeated ApprovalValue approval_values = 1;
394}
395
396// The request message for Issue.ListApprovalValues.
397// Next available tag: 2
398message ListApprovalValuesRequest {
399 // The name of the issue for which to list approval values.
400 string parent = 1 [
401 (google.api.resource_reference) = {type: "api.crbug.com/Issue"},
402 (google.api.field_behavior) = REQUIRED ];
403}
404
405// The response message for Issues.ListApprovalValues.
406// Next available tag: 2
407message ListApprovalValuesResponse {
408 // The approval values from the specified issue.
409 repeated ApprovalValue approval_values = 1;
410}
411
412// The request message for Issues.ModifyCommentState.
413// Next available tag: 3
414message ModifyCommentStateRequest {
415 // Resource name of the comment to modify state.
416 string name = 1 [
417 (google.api.resource_reference) = {type: "api.crbug.com/Comment"},
418 (google.api.field_behavior) = REQUIRED ];
419 // Requested state.
420 IssueContentState state = 2;
421}
422
423// The response message for Issues.ModifyCommentState.
424// Next available tag: 2
425message ModifyCommentStateResponse {
426 // The updated comment after modifying state.
427 Comment comment = 1;
428}
429
430// The request message for MakeIssueFromTemplate.
431// Next available tag: 5
432message MakeIssueFromTemplateRequest {
433 // Resource name of the template to use for filling in default values
434 // and adding approvals and phases.
435 string template = 1 [
436 (google.api.resource_reference) = { type: "api.crbug.com/Template" }
437 ];
438 // The issue differences relative to the `template.issue` default.
439 IssueDelta template_issue_delta = 2;
440 // Changes to fields belonging to approvals relative to template default.
441 // While ApprovalDelta can hold additional information, this method only
442 // allows adding and removing field values, all other deltas will be ignored.
443 repeated ApprovalDelta template_approval_deltas = 3;
444 // The issue description, will be saved as the first comment.
445 string description = 4;
446}
447
448// The request message for MakeIssue.
449// Next available tag: 5
450message MakeIssueRequest {
451 // The name of the project the issue should belong to.
452 string parent = 1 [
453 (google.api.resource_reference) = {type: "api.crbug.com/Project"},
454 (google.api.field_behavior) = REQUIRED ];
455 // The issue to be created.
456 Issue issue = 2;
457 // The issue description.
458 string description = 3;
459 // The type of notification the creation should trigger.
460 NotifyType notify_type = 4;
461}