package-version-suffix

Since 0.9.0 · In the rulesets: Strict at error, All at error

This rule checks whether the last component of the package name of a Protobuf file is a version, such as v1 or v1beta2.

Rule details

Versioned packages let a new, incompatible version of an API live next to the old one: the messages and services of acme.pets.v2 do not clash with those of acme.pets.v1, neither in the Protobuf namespace nor in the generated code.

The package-version-suffix rule reports Package '<name>' should end with a version component, e.g. v1 or v1beta1 when the last component of the package name is not a version. A version component is:

  • v followed by a major version that does not start with 0: v1, v2, v10,
  • optionally followed by a stability, alpha or beta, itself optionally followed by a number: v1alpha, v1beta2,
  • optionally with a point release between the major version and the stability: v1p1alpha, v1p2beta3. A point release requires a stability, so v1p1 is not a version,
  • or followed by test and any lowercase letters and digits: v2test, v1testfoo.

These are the versions buf accepts. Components such as v0, V1, version1, v1final and v1p1test are not versions.

Files without a package are not checked; see the package-defined rule.

The rule is part of the strict and all rulesets.

Turn the rule off if your APIs are versioned in another way, for example by the repository or the service name, or if the files are internal and never published.

Examples

Good.

syntax = "proto3";

package acme.pets.v1beta1;

message Pet {
  string name = 1;
}

Bad. The linter reports Package 'acme.pets' should end with a version component, e.g. v1 or v1beta1.

syntax = "proto3";

package acme.pets;

message Pet {
  string name = 1;
}

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.protobuf has the details.

commands:
  lint:
    protobuf:
      rules:
        package-version-suffix: off

Related rules

Was this helpful?