api/v3/api_proto/project_objects.proto

// 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;
}