package-version-suffix (Protobuf linter rule)

package-version-suffix

Since 0.9.0

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.

Configuration

This rule has no options.

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

When Not to Use It

You may disable this rule 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.

Compatibility