github.com/googleapis/api-linter@v1.65.2/docs/rules/0191/ruby-package.md (about)

     1  ---
     2  rule:
     3    aip: 191
     4    name: [core, '0191', ruby-package]
     5    summary: The `option ruby_package` annotation should be idiomatic if set.
     6  permalink: /191/ruby-package
     7  redirect_from:
     8    - /0191/ruby-package
     9  ---
    10  
    11  # Ruby package annotation
    12  
    13  This rule enforces that if a proto file for a public API surface sets
    14  `option ruby_package`, that it uses language idiomatic conventions, as mandated
    15  in [AIP-191][].
    16  
    17  ## Details
    18  
    19  This rule looks at each proto file, and complains if the `ruby_package` file
    20  annotation uses anything other than upper camel case, or includes characters
    21  other than letters, numbers, and `:`.
    22  
    23  It also ensures that versions with stability (e.g. `V1beta1`) are capitalized
    24  appropriately.
    25  
    26  ## Examples
    27  
    28  ### Case
    29  
    30  **Incorrect** code for this rule:
    31  
    32  ```proto
    33  // Incorrect.
    34  syntax = "proto3";
    35  
    36  package google.example.v1;
    37  
    38  option ruby_package = "google::example::v1";  // Should be UpperCamelCase.
    39  ```
    40  
    41  ```proto
    42  // Incorrect.
    43  syntax = "proto3";
    44  
    45  package google.example.v1;
    46  
    47  option ruby_package = "Google.Example.V1";  // Separator should be `::`.
    48  ```
    49  
    50  **Correct** code for this rule:
    51  
    52  ```proto
    53  // Correct.
    54  syntax = "proto3";
    55  
    56  package google.example.v1;
    57  
    58  option ruby_package = "Google::Example::V1";
    59  ```
    60  
    61  ### Versions with stability
    62  
    63  **Incorrect** code for this rule:
    64  
    65  ```proto
    66  // Incorrect.
    67  syntax = "proto3";
    68  
    69  package google.example.v1beta1;
    70  
    71  option ruby_package = "Google::Example::V1Beta1"; // Should be V1beta1.
    72  ```
    73  
    74  **Correct** code for this rule:
    75  
    76  ```proto
    77  // Correct.
    78  syntax = "proto3";
    79  
    80  package google.example.v1beta1;
    81  
    82  option ruby_package = "Google::Example::V1beta1";
    83  ```
    84  
    85  ## Known issues
    86  
    87  This rule will improperly complain if it encounters an acronym. For example, it
    88  will complain about `Google::Cloud::AutoML::V1`, preferring `AutoMl`. This lint
    89  rule **may** be disabled in this case.
    90  
    91  ## Disabling
    92  
    93  If you need to violate this rule, use a comment at the top of the file.
    94  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    95  
    96  ```proto
    97  // (-- api-linter: core::0191::ruby-package=disabled
    98  //     aip.dev/not-precedent: We need to do this because reasons. --)
    99  syntax = "proto3";
   100  
   101  package google.example.v1;
   102  
   103  option ruby_package = "google::example::v1";
   104  ```
   105  
   106  [aip-191]: https://aip.dev/191
   107  [aip.dev/not-precedent]: https://aip.dev/not-precedent