blob: 0c2a4c105abd469462e76b6be29801205b55626a [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 projects and their resources.
7
8syntax = "proto3";
9
10package monorail.v3;
11
12option go_package = "api/v3/api_proto";
13
14import "google/protobuf/timestamp.proto";
15import "google/api/field_behavior.proto";
16import "google/api/resource.proto";
17import "api/v3/api_proto/issue_objects.proto";
18import "api/v3/api_proto/permission_objects.proto";
19
20// The top level organization of issues in Monorail.
21//
22// See monorail/doc/userguide/concepts.md#Projects-and-roles.
23// and monorail/doc/userguide/project-owners.md#why-does-monorail-have-projects
24// Next available tag: 5
25message Project {
26 option (google.api.resource) = {
27 type: "api.crbug.com/Project"
28 pattern: "projects/{project}"
29 };
30
31 // Resource name of the project.
32 string name = 1;
33 // Display name of the project.
34 string display_name = 2 [(google.api.field_behavior) = IMMUTABLE];
35 // Summary of the project, ie describing what its use and purpose.
36 string summary = 3;
37 // URL pointing to this project's logo image.
38 string thumbnail_url = 4;
39}
40
41// Potential steps along the development process that an issue can be in.
42//
43// See monorail/doc/userguide/project-owners.md#How-to-configure-statuses
44// (-- aip.dev/not-precedent: "Status" should be reserved for HTTP/gRPC codes
45// per aip.dev/216. Monorail's Status preceded the AIP standards, and is
46// used extensively throughout the system.)
47// Next available tag: 7
48message StatusDef {
49 option (google.api.resource) = {
50 type: "api.crbug.com/StatusDef"
51 pattern: "projects/{project}/statusDefs/{status_def}"
52 };
53
54 // Type of this status.
55 // Next available tag: 4
56 enum StatusDefType {
57 // Default enum value. This value is unused.
58 STATUS_DEF_TYPE_UNSPECIFIED = 0;
59 // This status means issue is open.
60 OPEN = 1;
61 // This status means issue is closed.
62 CLOSED = 2;
63 // This status means issue is merged into another.
64 MERGED = 3;
65 }
66
67 // State of this status.
68 // Next available tag: 3
69 enum StatusDefState {
70 // Default value. This value is unused.
71 STATUS_DEF_STATE_UNSPECIFIED = 0;
72 // This status is deprecated
73 DEPRECATED = 1;
74 // This status is not deprecated
75 ACTIVE = 2;
76 }
77
78 // Resource name of the status.
79 string name = 1;
80 // String value of the status.
81 string value = 2;
82 // Type of this status.
83 StatusDefType type = 3;
84 // Sorting rank of this status. If we sort issues by status
85 // this rank determines the sort order rather than status value.
86 uint32 rank = 4;
87 // Brief explanation of this status.
88 string docstring = 5;
89 // State of this status.
90 StatusDefState state = 6;
91}
92
93// Well-known labels that can be applied to issues within the project.
94//
95// See monorail/doc/userguide/concepts.md#issue-fields-and-labels.
96// Next available tag: 5
97// Labels defined in this project.
98message LabelDef {
99
100 option (google.api.resource) = {
101 type: "api.crbug.com/LabelDef"
102 pattern: "projects/{project}/labelDefs/{label_def}"
103 };
104
105 // State of this label.
106 // Next available tag: 3
107 enum LabelDefState {
108 // Default enum value. This value is unused.
109 LABEL_DEF_STATE_UNSPECIFIED = 0;
110 // This label is deprecated
111 DEPRECATED = 1;
112 // This label is not deprecated
113 ACTIVE = 2;
114 }
115
116 // Resource name of the label.
117 string name = 1;
118 // String value of the label.
119 string value = 2;
120 // Brief explanation of this label.
121 string docstring = 3;
122 // State of this label.
123 LabelDefState state = 4;
124}
125
126// Custom fields defined for the project.
127//
128// See monorail/doc/userguide/concepts.md#issue-fields-and-labels.
129// Check bugs.chromium.org/p/{project}/adminLabels to see the FieldDef IDs.
130// If your code needs to call multiple monorail instances
131// (e.g. monorail-{prod|staging|dev}) FieldDef IDs for FieldDefs
132// with the same display_name will differ between each monorail
133// instance. To see what FieldDef ID to use when calling staging
134// you must check bugs-staging.chromium.org/p/{project}/adminLabels.
135// Next available tag: 15
136message FieldDef {
137 option (google.api.resource) = {
138 type: "api.crbug.com/FieldDef"
139 pattern: "projects/{project}/fieldDefs/{field_def_id}"
140 };
141
142 // Resource name of the field.
143 string name = 1;
144 // Display name of the field.
145 string display_name = 2 [(google.api.field_behavior) = IMMUTABLE];
146 // Brief explanation of this field.
147 string docstring = 3;
148 // Type of this field.
149 // Next available tag: 7
150 enum Type {
151 // Default enum value. This value is unused.
152 TYPE_UNSPECIFIED = 0;
153 // This field can be filled only with enumerated option(s).
154 ENUM = 1;
155 // This field can be filled with integer(s).
156 INT = 2;
157 // This field can be filled with string(s).
158 STR = 3;
159 // This field can be filled with user(s).
160 USER = 4;
161 // This field can be filled with date(s).
162 DATE = 5;
163 // This field can be filled with URL(s).
164 URL = 6;
165 }
166 Type type = 4 [(google.api.field_behavior) = IMMUTABLE];
167
168 // Type of issue this field applies: ie Bug or Enhancement.
169 // Note: type is indicated by any "Type-foo" label or "Type" custom field.
170 string applicable_issue_type = 5;
171 // Administrators of this field.
172 repeated string admins = 6 [
173 (google.api.resource_reference) = { type: "api.crbug.com/User" }
174 ];
175
176 // Traits of this field, ie is required or can support multiple values.
177 // Next available tag: 6
178 enum Traits {
179 // Default enum value. This value is unused.
180 TRAITS_UNSPECIFIED = 0;
181 // This field must be filled out in issues where it's applicable.
182 REQUIRED = 1;
183 // This field defaults to hidden.
184 DEFAULT_HIDDEN = 2;
185 // This field can have multiple values.
186 MULTIVALUED = 3;
187 // This is a phase field, meaning it is repeated for each phase of an
188 // approval process. It cannot be the child of a particular approval.
189 PHASE = 4;
190 // Values of this field can only be edited in issues/templates by editors.
191 // Project owners and field admins are not subject of this restriction.
192 RESTRICTED = 5;
193 }
194 repeated Traits traits = 7;
195
196 // ApprovalDef that this field belongs to, if applicable.
197 // A field may not both have `approval_parent` set and have the PHASE trait.
198 string approval_parent = 8 [
199 (google.api.resource_reference) = { type: "api.crbug.com/ApprovalDef" },
200 (google.api.field_behavior) = IMMUTABLE
201 ];
202
203 // Settings specific to enum type fields.
204 // Next available tag: 2
205 message EnumTypeSettings {
206 // One available choice for an enum field.
207 // Next available tag: 3
208 message Choice {
209 // Value of this choice.
210 string value = 1;
211 // Brief explanation of this choice.
212 string docstring = 2;
213 }
214 repeated Choice choices = 1;
215 }
216 EnumTypeSettings enum_settings = 9;
217
218 // Settings specific to int type fields.
219 // Next available tag: 3
220 message IntTypeSettings {
221 // Minimum value that this field can have.
222 int32 min_value = 1;
223 // Maximum value that this field can have.
224 int32 max_value = 2;
225 }
226 IntTypeSettings int_settings = 10;
227
228 // Settings specific to str type fields.
229 // Next available tag: 2
230 message StrTypeSettings {
231 // Regex that this field value(s) must match.
232 string regex = 1;
233 }
234 StrTypeSettings str_settings = 11;
235
236 // Settings specific to user type fields.
237 // Next available tag: 5
238 message UserTypeSettings {
239 // Event that triggers a notification.
240 // Next available tag: 3
241 enum NotifyTriggers {
242 // Default notify trigger value. This value is unused.
243 NOTIFY_TRIGGERS_UNSPECIFIED = 0;
244 // There are no notifications.
245 NEVER = 1;
246 // Notify whenever any comment is made.
247 ANY_COMMENT = 2;
248 }
249 NotifyTriggers notify_triggers = 1;
250 // Field value(s) can only be set to users that fulfill the role
251 // requirements.
252 // Next available tag: 3
253 enum RoleRequirements {
254 // Default role requirement value. This value is unused.
255 ROLE_REQUIREMENTS_UNSPECIFIED = 0;
256 // There is no requirement.
257 NO_ROLE_REQUIREMENT = 1;
258 // Field value(s) can only be set to users who are members.
259 PROJECT_MEMBER = 2;
260 }
261 RoleRequirements role_requirements = 2;
262 // User(s) named in this field are granted this permission in the issue.
263 string grants_perm = 3;
264 // Field value(s) can only be set to users with this permission.
265 string needs_perm = 4;
266 }
267 UserTypeSettings user_settings = 12;
268
269 // Settings specific to date type fields.
270 // Next available tag: 2
271 message DateTypeSettings {
272 // Action to do when a date field value arrives.
273 // Next available tag: 4
274 enum DateAction {
275 // Default date action value. This value is unused.
276 DATE_ACTION_UNSPECIFIED = 0;
277 // No action will be taken when a date arrives.
278 NO_ACTION = 1;
279 // Notify owner only when a date arrives.
280 NOTIFY_OWNER = 2;
281 // Notify all participants when a date arrives.
282 NOTIFY_PARTICIPANTS = 3;
283 }
284 DateAction date_action = 1;
285 }
286 DateTypeSettings date_settings = 13;
287
288 // Editors of this field, only for RESTRICTED fields.
289 repeated string editors = 14 [
290 (google.api.resource_reference) = { type: "api.crbug.com/User" }
291 ];
292}
293
294// A high level definition of the part of the software affected by an issue.
295//
296// See monorail/doc/userguide/project-owners.md#how-to-configure-components.
297// Check crbug.com/p/{project}/adminComponents to see the ComponenttDef IDs.
298// Next available tag: 12
299message ComponentDef {
300 option (google.api.resource) = {
301 type: "api.crbug.com/ComponentDef"
302 pattern: "projects/{project}/componentDefs/{component_def_id}"
303 };
304
305 // The current state of the component definition.
306 // Next available tag: 3
307 enum ComponentDefState {
308 // Default enum value. This value is unused.
309 COMPONENT_DEF_STATE_UNSPECIFIED = 0;
310 // This component is deprecated
311 DEPRECATED = 1;
312 // This component is not deprecated
313 ACTIVE = 2;
314 }
315
316 // Resource name of the component, aka identifier.
317 // the API will always return ComponentDef names with format:
318 // projects/{project}/componentDefs/<component_def_id>.
319 // However the API will accept ComponentDef names with formats:
320 // projects/{project}/componentDefs/<component_def_id>|<value>.
321 string name = 1;
322 // String value of the component, ie 'Tools>Stability' or 'Blink'.
323 string value = 2;
324 // Brief explanation of this component.
325 string docstring = 3;
326 // Administrators of this component.
327 repeated string admins = 4 [
328 (google.api.resource_reference) = { type: "api.crbug.com/User" }
329 ];
330 // Auto cc'ed users of this component.
331 repeated string ccs = 5 [
332 (google.api.resource_reference) = { type: "api.crbug.com/User" }
333 ];
334 // State of this component.
335 ComponentDefState state = 6;
336 // The user that created this component.
337 string creator = 7 [
338 (google.api.resource_reference) = { type: "api.crbug.com/User" },
339 (google.api.field_behavior) = OUTPUT_ONLY
340 ];
341 // The user that last modified this component.
342 string modifier = 8 [
343 (google.api.resource_reference) = { type: "api.crbug.com/User" },
344 (google.api.field_behavior) = OUTPUT_ONLY
345 ];
346 // The time this component was created.
347 google.protobuf.Timestamp create_time = 9 [
348 (google.api.field_behavior) = OUTPUT_ONLY
349 ];
350 // The time this component was last modified.
351 google.protobuf.Timestamp modify_time = 10 [
352 (google.api.field_behavior) = OUTPUT_ONLY
353 ];
354 // Labels that auto-apply to issues in this component.
355 repeated string labels = 11;
356}
357
358// Defines approvals that issues within the project may need.
359// See monorail/doc/userguide/concepts.md#issue-approvals-and-gates and
360// monorail/doc/userguide/project-owners.md#How-to-configure-approvals
361// Check bugs.chromium.org/p/{project}/adminLabels to see the ApprovalDef IDs.
362// If your code needs to call multiple monorail instances
363// (e.g. monorail-{prod|staging|dev}) ApprovalDef IDs for ApprovalDefs
364// with the same display_name will differ between each monorail
365// instance. To see what ApprovalDef ID to use when calling staging
366// you must check bugs-staging.chromium.org/p/{project}/adminLabels.
367// Next available tag: 7
368message ApprovalDef {
369 option (google.api.resource) = {
370 type: "api.crbug.com/ApprovalDef"
371 pattern: "projects/{project}/approvalDefs/{approval_def_id}"
372 };
373
374 // Resource name of the approval.
375 string name = 1;
376 // Display name of the field.
377 string display_name = 2 [(google.api.field_behavior) = IMMUTABLE];
378 // Brief explanation of this field.
379 string docstring = 3;
380 // Information approvers need from requester.
381 // May be adjusted on the issue after creation.
382 string survey = 4;
383 // Default list of users who can approve this field.
384 // May be adjusted on the issue after creation.
385 repeated string approvers = 5 [
386 (google.api.resource_reference) = { type: "api.crbug.com/User" }
387 ];
388 // Administrators of this field.
389 repeated string admins = 6 [
390 (google.api.resource_reference) = { type: "api.crbug.com/User" }
391 ];
392}
393
394
395// Defines saved queries that belong to a project
396//
397// Next available tag: 4
398message ProjectSavedQuery {
399 option (google.api.resource) = {
400 type: "api.crbug.com/ProjectSavedQuery"
401 pattern: "projects/{project}/savedQueries/{saved_query_id}"
402 };
403
404 // Resource name of this saved query.
405 string name = 1;
406 // Display name of this saved query, ie 'open issues'.
407 string display_name = 2;
408 // Search term of this saved query.
409 string query = 3;
410}
411
412
413// Defines a template for filling issues.
414// Next available tag: 10
415message IssueTemplate {
416 option (google.api.resource) = {
417 type: "api.crbug.com/IssueTemplate"
418 pattern: "projects/{project}/templates/{template_id}"
419 };
420 // Resource name of the template.
421 string name = 1;
422 // Display name of this template.
423 string display_name = 2 [(google.api.field_behavior) = IMMUTABLE];
424 // Canonical Issue for this template.
425 Issue issue = 3;
426 // ApprovalValues to be created with the issue when using this template.
427 repeated ApprovalValue approval_values = 9;
428 // Boolean indicating subsequent issue creation must have delta in summary.
429 bool summary_must_be_edited = 4;
430 // Visibility permission of template.
431 // Next available tag: 3
432 enum TemplatePrivacy {
433 // This value is unused.
434 TEMPLATE_PRIVACY_UNSPECIFIED = 0;
435 // Owner project members may view this template.
436 MEMBERS_ONLY = 1;
437 // Anyone on the web can view this template.
438 PUBLIC = 2;
439 }
440 TemplatePrivacy template_privacy = 5;
441 // Indicator of who if anyone should be the default owner of the issue
442 // created with this template.
443 // Next available tag: 2
444 enum DefaultOwner {
445 // There is no default owner.
446 // This value is used if the default owner is omitted.
447 DEFAULT_OWNER_UNSPECIFIED = 0;
448 // The owner should default to the Issue reporter if the reporter is a
449 // member of the project.
450 PROJECT_MEMBER_REPORTER = 1;
451 }
452 DefaultOwner default_owner = 6;
453 // Boolean indicating whether issue must have a component.
454 bool component_required = 7;
455 // Names of Users who can administer this template.
456 repeated string admins = 8 [
457 (google.api.resource_reference) = { type: "api.crbug.com/User" }];
458}
459
460
461// Defines configurations of a project
462//
463// Next available tag: 11
464message ProjectConfig {
465 option (google.api.resource) = {
466 type: "api.crbug.com/ProjectConfig"
467 pattern: "projects/{project}/config"
468 };
469
470 // Resource name of the project config.
471 string name = 1;
472 // Set of label prefixes that only apply once per issue.
473 // E.g. priority, since no issue can be both Priority-High and Priority-Low.
474 repeated string exclusive_label_prefixes = 2;
475 // Default search query for this project's members.
476 string member_default_query = 3;
477 // TODO(crbug.com/monorail/7517): consider using IssuesListColumn
478 // Default sort specification for this project.
479 string default_sort = 4;
480 // Default columns for displaying issue list for this project.
481 repeated IssuesListColumn default_columns = 5;
482 // Grid view configurations.
483 // Next available tag: 3
484 message GridViewConfig {
485 // Default column dimension in grid view for this project.
486 string default_x_attr = 1;
487 // Default row dimension in grid view for this project.
488 string default_y_attr = 2;
489 }
490 GridViewConfig project_grid_config = 6;
491 // Default template used for issue entry for members of this project.
492 string member_default_template = 7 [
493 (google.api.resource_reference) = { type: "api.crbug.com/Template" }];
494 // Default template used for issue entry for non-members of this project.
495 string non_members_default_template = 8 [
496 (google.api.resource_reference) = { type: "api.crbug.com/Template" }];
497 // URL to browse project's source code revisions for any given revnum.
498 // E.g. https://crrev.com/{revnum}
499 string revision_url_format = 9;
500 // A project's custom URL for the "New issue" link, only if specified.
501 string custom_issue_entry_url = 10;
502}
503
504// Specifies info for a member of a project.
505//
506// Next available tag: 7
507message ProjectMember {
508 // Resource name of the Project Member.
509 // projects/{project}/members/{user_id}
510 string name = 1;
511 // The role the user has in the project.
512 // Next available tag: 4
513 enum ProjectRole {
514 // The user has no role in the project.
515 PROJECT_ROLE_UNSPECIFIED = 0;
516 // The user can make any changes to the project.
517 OWNER = 1;
518 // The user may participate in the project but may not edit the project.
519 COMMITTER = 2;
520 // The user starts with the same permissions as a non-member.
521 CONTRIBUTOR = 3;
522 }
523 ProjectRole role = 2;
524 // Which built-in/standard permissions the user has set.
525 repeated Permission standard_perms = 3;
526 // Custom permissions defined for the user.
527 // eg. "Google" in "Restrict-View-Google" is an example custom permission.
528 repeated string custom_perms = 4;
529 // Annotations about a user configured by project owners.
530 // Visible to anyone who can see the project's settings.
531 string notes = 5;
532 // Whether the user should show up in autocomplete.
533 // Next available tag: 3
534 enum AutocompleteVisibility {
535 // No autocomplete visibility value specified.
536 AUTOCOMPLETE_VISIBILITY_UNSPECIFIED = 0;
537 // The user should not show up in autocomplete.
538 HIDDEN = 1;
539 // The user may show up in autocomplete.
540 SHOWN = 2;
541 }
542 AutocompleteVisibility include_in_autocomplete = 6;
543}