FAQ

buf.yaml version

You may have recently gotten the following warning:

WARN File "buf.yaml" has no version set. Please add "version: v1beta1". See https://buf.build/docs/faq for more details.

We have added the concept of version to the configuration. For a given version, the following will not change:

  • Configuration file layout
  • Default configuration files
  • Lint and breaking checkers, and their associated categories.

Our goal at Buf is to never break users. You should be able to upgrade Buf, and expect the same results, forever. In this spirit, we want to make sure that upgrading Buf does not result in any configuration differences, and does not result in different lint or breaking change results.

We also need to be able to enhance the lint and breaking change functionality, and improve on the configuration shape as well. To accomplish this, while not breaking users who have come to rely on the existing shape and checkers, we have added this version. The only currently-available version is v1beta1.

The v1beta1 version will be supported forever. This will not be removed when we hit v1.0. Having a version set in your configuration is currently optional, however we will require having a version as of v1.0. This will be one of the only (if not the only) breaking changes between the beta and v1.0.

To prepare for this, and to remove this warning, just add a version to the top of your buf.yaml:

version: v1beta1

As a simple one-liner to do so, run the following:

$ cat <(echo version: v1beta1) buf.yaml > buf.yaml.tmp && mv buf.yaml.tmp buf.yaml

A version can (and should) also be added to the protoc plugin options. For example:

$ protoc -I . \
--buf-check-lint_out=. \
'--buf-check-lint_opt={"input_config":{"version":"v1beta1","lint":{"use":["ENUM_NO_ALLOW_ALIAS"]}}}' \
$(find . -name '*.proto')

We apologize for any inconvenience this warning may have caused.