blob: 21f4bc6104d0cb94e2b44022f0cb698dffb15ab8 [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 projects and their resources.
syntax = "proto3";
package monorail.v3;
option go_package = "infra/monorailv2/api/v3/api_proto";
import "google/protobuf/timestamp.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "api/v3/api_proto/issue_objects.proto";
import "api/v3/api_proto/permission_objects.proto";
// The top level organization of issues in Monorail.
//
// See monorail/doc/userguide/concepts.md#Projects-and-roles.
// and monorail/doc/userguide/project-owners.md#why-does-monorail-have-projects
// Next available tag: 5
message Project {
option (google.api.resource) = {
type: "api.crbug.com/Project"
pattern: "projects/{project}"
};
// Resource name of the project.
string name = 1;
// Display name of the project.
string display_name = 2 [(google.api.field_behavior) = IMMUTABLE];
// Summary of the project, ie describing what its use and purpose.
string summary = 3;
// URL pointing to this project's logo image.
string thumbnail_url = 4;
}
// Potential steps along the development process that an issue can be in.
//
// See monorail/doc/userguide/project-owners.md#How-to-configure-statuses
// (-- aip.dev/not-precedent: "Status" should be reserved for HTTP/gRPC codes
// per aip.dev/216. Monorail's Status preceded the AIP standards, and is
// used extensively throughout the system.)
// Next available tag: 7
message StatusDef {
option (google.api.resource) = {
type: "api.crbug.com/StatusDef"
pattern: "projects/{project}/statusDefs/{status_def}"
};
// Type of this status.
// Next available tag: 4
enum StatusDefType {
// Default enum value. This value is unused.
STATUS_DEF_TYPE_UNSPECIFIED = 0;
// This status means issue is open.
OPEN = 1;
// This status means issue is closed.
CLOSED = 2;
// This status means issue is merged into another.
MERGED = 3;
}
// State of this status.
// Next available tag: 3
enum StatusDefState {
// Default value. This value is unused.
STATUS_DEF_STATE_UNSPECIFIED = 0;
// This status is deprecated
DEPRECATED = 1;
// This status is not deprecated
ACTIVE = 2;
}
// Resource name of the status.
string name = 1;
// String value of the status.
string value = 2;
// Type of this status.
StatusDefType type = 3;
// Sorting rank of this status. If we sort issues by status
// this rank determines the sort order rather than status value.
uint32 rank = 4;
// Brief explanation of this status.
string docstring = 5;
// State of this status.
StatusDefState state = 6;
}
// Well-known labels that can be applied to issues within the project.
//
// See monorail/doc/userguide/concepts.md#issue-fields-and-labels.
// Next available tag: 5
// Labels defined in this project.
message LabelDef {
option (google.api.resource) = {
type: "api.crbug.com/LabelDef"
pattern: "projects/{project}/labelDefs/{label_def}"
};
// State of this label.
// Next available tag: 3
enum LabelDefState {
// Default enum value. This value is unused.
LABEL_DEF_STATE_UNSPECIFIED = 0;
// This label is deprecated
DEPRECATED = 1;
// This label is not deprecated
ACTIVE = 2;
}
// Resource name of the label.
string name = 1;
// String value of the label.
string value = 2;
// Brief explanation of this label.
string docstring = 3;
// State of this label.
LabelDefState state = 4;
}
// Custom fields defined for the project.
//
// See monorail/doc/userguide/concepts.md#issue-fields-and-labels.
// Check bugs.chromium.org/p/{project}/adminLabels to see the FieldDef IDs.
// If your code needs to call multiple monorail instances
// (e.g. monorail-{prod|staging|dev}) FieldDef IDs for FieldDefs
// with the same display_name will differ between each monorail
// instance. To see what FieldDef ID to use when calling staging
// you must check bugs-staging.chromium.org/p/{project}/adminLabels.
// Next available tag: 15
message FieldDef {
option (google.api.resource) = {
type: "api.crbug.com/FieldDef"
pattern: "projects/{project}/fieldDefs/{field_def_id}"
};
// Resource name of the field.
string name = 1;
// Display name of the field.
string display_name = 2 [(google.api.field_behavior) = IMMUTABLE];
// Brief explanation of this field.
string docstring = 3;
// Type of this field.
// Next available tag: 7
enum Type {
// Default enum value. This value is unused.
TYPE_UNSPECIFIED = 0;
// This field can be filled only with enumerated option(s).
ENUM = 1;
// This field can be filled with integer(s).
INT = 2;
// This field can be filled with string(s).
STR = 3;
// This field can be filled with user(s).
USER = 4;
// This field can be filled with date(s).
DATE = 5;
// This field can be filled with URL(s).
URL = 6;
}
Type type = 4 [(google.api.field_behavior) = IMMUTABLE];
// Type of issue this field applies: ie Bug or Enhancement.
// Note: type is indicated by any "Type-foo" label or "Type" custom field.
string applicable_issue_type = 5;
// Administrators of this field.
repeated string admins = 6 [
(google.api.resource_reference) = { type: "api.crbug.com/User" }
];
// Traits of this field, ie is required or can support multiple values.
// Next available tag: 6
enum Traits {
// Default enum value. This value is unused.
TRAITS_UNSPECIFIED = 0;
// This field must be filled out in issues where it's applicable.
REQUIRED = 1;
// This field defaults to hidden.
DEFAULT_HIDDEN = 2;
// This field can have multiple values.
MULTIVALUED = 3;
// This is a phase field, meaning it is repeated for each phase of an
// approval process. It cannot be the child of a particular approval.
PHASE = 4;
// Values of this field can only be edited in issues/templates by editors.
// Project owners and field admins are not subject of this restriction.
RESTRICTED = 5;
}
repeated Traits traits = 7;
// ApprovalDef that this field belongs to, if applicable.
// A field may not both have `approval_parent` set and have the PHASE trait.
string approval_parent = 8 [
(google.api.resource_reference) = { type: "api.crbug.com/ApprovalDef" },
(google.api.field_behavior) = IMMUTABLE
];
// Settings specific to enum type fields.
// Next available tag: 2
message EnumTypeSettings {
// One available choice for an enum field.
// Next available tag: 3
message Choice {
// Value of this choice.
string value = 1;
// Brief explanation of this choice.
string docstring = 2;
}
repeated Choice choices = 1;
}
EnumTypeSettings enum_settings = 9;
// Settings specific to int type fields.
// Next available tag: 3
message IntTypeSettings {
// Minimum value that this field can have.
int32 min_value = 1;
// Maximum value that this field can have.
int32 max_value = 2;
}
IntTypeSettings int_settings = 10;
// Settings specific to str type fields.
// Next available tag: 2
message StrTypeSettings {
// Regex that this field value(s) must match.
string regex = 1;
}
StrTypeSettings str_settings = 11;
// Settings specific to user type fields.
// Next available tag: 5
message UserTypeSettings {
// Event that triggers a notification.
// Next available tag: 3
enum NotifyTriggers {
// Default notify trigger value. This value is unused.
NOTIFY_TRIGGERS_UNSPECIFIED = 0;
// There are no notifications.
NEVER = 1;
// Notify whenever any comment is made.
ANY_COMMENT = 2;
}
NotifyTriggers notify_triggers = 1;
// Field value(s) can only be set to users that fulfill the role
// requirements.
// Next available tag: 3
enum RoleRequirements {
// Default role requirement value. This value is unused.
ROLE_REQUIREMENTS_UNSPECIFIED = 0;
// There is no requirement.
NO_ROLE_REQUIREMENT = 1;
// Field value(s) can only be set to users who are members.
PROJECT_MEMBER = 2;
}
RoleRequirements role_requirements = 2;
// User(s) named in this field are granted this permission in the issue.
string grants_perm = 3;
// Field value(s) can only be set to users with this permission.
string needs_perm = 4;
}
UserTypeSettings user_settings = 12;
// Settings specific to date type fields.
// Next available tag: 2
message DateTypeSettings {
// Action to do when a date field value arrives.
// Next available tag: 4
enum DateAction {
// Default date action value. This value is unused.
DATE_ACTION_UNSPECIFIED = 0;
// No action will be taken when a date arrives.
NO_ACTION = 1;
// Notify owner only when a date arrives.
NOTIFY_OWNER = 2;
// Notify all participants when a date arrives.
NOTIFY_PARTICIPANTS = 3;
}
DateAction date_action = 1;
}
DateTypeSettings date_settings = 13;
// Editors of this field, only for RESTRICTED fields.
repeated string editors = 14 [
(google.api.resource_reference) = { type: "api.crbug.com/User" }
];
}
// A high level definition of the part of the software affected by an issue.
//
// See monorail/doc/userguide/project-owners.md#how-to-configure-components.
// Check crbug.com/p/{project}/adminComponents to see the ComponenttDef IDs.
// Next available tag: 12
message ComponentDef {
option (google.api.resource) = {
type: "api.crbug.com/ComponentDef"
pattern: "projects/{project}/componentDefs/{component_def_id}"
};
// The current state of the component definition.
// Next available tag: 3
enum ComponentDefState {
// Default enum value. This value is unused.
COMPONENT_DEF_STATE_UNSPECIFIED = 0;
// This component is deprecated
DEPRECATED = 1;
// This component is not deprecated
ACTIVE = 2;
}
// Resource name of the component, aka identifier.
// the API will always return ComponentDef names with format:
// projects/{project}/componentDefs/<component_def_id>.
// However the API will accept ComponentDef names with formats:
// projects/{project}/componentDefs/<component_def_id>|<value>.
string name = 1;
// String value of the component, ie 'Tools>Stability' or 'Blink'.
string value = 2;
// Brief explanation of this component.
string docstring = 3;
// Administrators of this component.
repeated string admins = 4 [
(google.api.resource_reference) = { type: "api.crbug.com/User" }
];
// Auto cc'ed users of this component.
repeated string ccs = 5 [
(google.api.resource_reference) = { type: "api.crbug.com/User" }
];
// State of this component.
ComponentDefState state = 6;
// The user that created this component.
string creator = 7 [
(google.api.resource_reference) = { type: "api.crbug.com/User" },
(google.api.field_behavior) = OUTPUT_ONLY
];
// The user that last modified this component.
string modifier = 8 [
(google.api.resource_reference) = { type: "api.crbug.com/User" },
(google.api.field_behavior) = OUTPUT_ONLY
];
// The time this component was created.
google.protobuf.Timestamp create_time = 9 [
(google.api.field_behavior) = OUTPUT_ONLY
];
// The time this component was last modified.
google.protobuf.Timestamp modify_time = 10 [
(google.api.field_behavior) = OUTPUT_ONLY
];
// Labels that auto-apply to issues in this component.
repeated string labels = 11;
}
// Defines approvals that issues within the project may need.
// See monorail/doc/userguide/concepts.md#issue-approvals-and-gates and
// monorail/doc/userguide/project-owners.md#How-to-configure-approvals
// Check bugs.chromium.org/p/{project}/adminLabels to see the ApprovalDef IDs.
// If your code needs to call multiple monorail instances
// (e.g. monorail-{prod|staging|dev}) ApprovalDef IDs for ApprovalDefs
// with the same display_name will differ between each monorail
// instance. To see what ApprovalDef ID to use when calling staging
// you must check bugs-staging.chromium.org/p/{project}/adminLabels.
// Next available tag: 7
message ApprovalDef {
option (google.api.resource) = {
type: "api.crbug.com/ApprovalDef"
pattern: "projects/{project}/approvalDefs/{approval_def_id}"
};
// Resource name of the approval.
string name = 1;
// Display name of the field.
string display_name = 2 [(google.api.field_behavior) = IMMUTABLE];
// Brief explanation of this field.
string docstring = 3;
// Information approvers need from requester.
// May be adjusted on the issue after creation.
string survey = 4;
// Default list of users who can approve this field.
// May be adjusted on the issue after creation.
repeated string approvers = 5 [
(google.api.resource_reference) = { type: "api.crbug.com/User" }
];
// Administrators of this field.
repeated string admins = 6 [
(google.api.resource_reference) = { type: "api.crbug.com/User" }
];
}
// Defines saved queries that belong to a project
//
// Next available tag: 4
message ProjectSavedQuery {
option (google.api.resource) = {
type: "api.crbug.com/ProjectSavedQuery"
pattern: "projects/{project}/savedQueries/{saved_query_id}"
};
// Resource name of this saved query.
string name = 1;
// Display name of this saved query, ie 'open issues'.
string display_name = 2;
// Search term of this saved query.
string query = 3;
}
// Defines a template for filling issues.
// Next available tag: 10
message IssueTemplate {
option (google.api.resource) = {
type: "api.crbug.com/IssueTemplate"
pattern: "projects/{project}/templates/{template_id}"
};
// Resource name of the template.
string name = 1;
// Display name of this template.
string display_name = 2 [(google.api.field_behavior) = IMMUTABLE];
// Canonical Issue for this template.
Issue issue = 3;
// ApprovalValues to be created with the issue when using this template.
repeated ApprovalValue approval_values = 9;
// Boolean indicating subsequent issue creation must have delta in summary.
bool summary_must_be_edited = 4;
// Visibility permission of template.
// Next available tag: 3
enum TemplatePrivacy {
// This value is unused.
TEMPLATE_PRIVACY_UNSPECIFIED = 0;
// Owner project members may view this template.
MEMBERS_ONLY = 1;
// Anyone on the web can view this template.
PUBLIC = 2;
}
TemplatePrivacy template_privacy = 5;
// Indicator of who if anyone should be the default owner of the issue
// created with this template.
// Next available tag: 2
enum DefaultOwner {
// There is no default owner.
// This value is used if the default owner is omitted.
DEFAULT_OWNER_UNSPECIFIED = 0;
// The owner should default to the Issue reporter if the reporter is a
// member of the project.
PROJECT_MEMBER_REPORTER = 1;
}
DefaultOwner default_owner = 6;
// Boolean indicating whether issue must have a component.
bool component_required = 7;
// Names of Users who can administer this template.
repeated string admins = 8 [
(google.api.resource_reference) = { type: "api.crbug.com/User" }];
}
// Defines configurations of a project
//
// Next available tag: 11
message ProjectConfig {
option (google.api.resource) = {
type: "api.crbug.com/ProjectConfig"
pattern: "projects/{project}/config"
};
// Resource name of the project config.
string name = 1;
// Set of label prefixes that only apply once per issue.
// E.g. priority, since no issue can be both Priority-High and Priority-Low.
repeated string exclusive_label_prefixes = 2;
// Default search query for this project's members.
string member_default_query = 3;
// TODO(crbug.com/monorail/7517): consider using IssuesListColumn
// Default sort specification for this project.
string default_sort = 4;
// Default columns for displaying issue list for this project.
repeated IssuesListColumn default_columns = 5;
// Grid view configurations.
// Next available tag: 3
message GridViewConfig {
// Default column dimension in grid view for this project.
string default_x_attr = 1;
// Default row dimension in grid view for this project.
string default_y_attr = 2;
}
GridViewConfig project_grid_config = 6;
// Default template used for issue entry for members of this project.
string member_default_template = 7 [
(google.api.resource_reference) = { type: "api.crbug.com/Template" }];
// Default template used for issue entry for non-members of this project.
string non_members_default_template = 8 [
(google.api.resource_reference) = { type: "api.crbug.com/Template" }];
// URL to browse project's source code revisions for any given revnum.
// E.g. https://crrev.com/{revnum}
string revision_url_format = 9;
// A project's custom URL for the "New issue" link, only if specified.
string custom_issue_entry_url = 10;
}
// Specifies info for a member of a project.
//
// Next available tag: 7
message ProjectMember {
// Resource name of the Project Member.
// projects/{project}/members/{user_id}
string name = 1;
// The role the user has in the project.
// Next available tag: 4
enum ProjectRole {
// The user has no role in the project.
PROJECT_ROLE_UNSPECIFIED = 0;
// The user can make any changes to the project.
OWNER = 1;
// The user may participate in the project but may not edit the project.
COMMITTER = 2;
// The user starts with the same permissions as a non-member.
CONTRIBUTOR = 3;
}
ProjectRole role = 2;
// Which built-in/standard permissions the user has set.
repeated Permission standard_perms = 3;
// Custom permissions defined for the user.
// eg. "Google" in "Restrict-View-Google" is an example custom permission.
repeated string custom_perms = 4;
// Annotations about a user configured by project owners.
// Visible to anyone who can see the project's settings.
string notes = 5;
// Whether the user should show up in autocomplete.
// Next available tag: 3
enum AutocompleteVisibility {
// No autocomplete visibility value specified.
AUTOCOMPLETE_VISIBILITY_UNSPECIFIED = 0;
// The user should not show up in autocomplete.
HIDDEN = 1;
// The user may show up in autocomplete.
SHOWN = 2;
}
AutocompleteVisibility include_in_autocomplete = 6;
}