Skip to main content

Migration Guide (v1beta1 -> v1)

Several changes were made between v1beta1 and v1, but migrating between them is easy. This guide will walk through exactly what changed, and what you need to change when upgrading from v1beta1 to v1.

Automatic migration#

The buf config migrate-v1beta1 command automatically migrates all of your buf configuration files from v1beta1 to v1.

For example, consider the following buf.yaml with multiple roots:

version: v1beta1build:  roots:    - proto    - vendor/googleapislint:  use:    - DEFAULTbreaking:  use:    - FILE
.├── buf.gen.yaml├── buf.lock├── buf.yaml├── proto│   └── acme│       └── pet│           └── v1│               └── pet.proto└── vendor    └── googleapis        └── google            └── type                └── datetime.proto

You can automatically migrate all of the files from v1beta1 to v1 by simply running buf config migrate-v1beta1 in a directory containing a buf.yaml, buf.lock, or buf.gen.yaml:

$ buf config migrate-v1beta1Successfully migrated your buf.yaml, buf.gen.yaml, and buf.lock to v1.

You'll notice that the filenames are equivalent, but the files have been rearranged and a new was created:

.├── buf.gen.yaml├──├── proto│   ├── acme│   │   └── pet│   │       └── v1│   │           └── pet.proto│   ├── buf.lock│   └── buf.yaml└── vendor    └── googleapis        ├── buf.lock        ├── buf.yaml        └── google            └── type                └── datetime.proto

The following sections will explain what changed between v1beta1 and v1 in more detail.


The buf.yaml configuration file is largely unchanged, but a few significant changes were made to build roots, as well as lint and breaking rules.


The only structural change made to the buf.yaml file for v1 was the removal of build.roots. Previously, users could configure multiple roots for a single buf.yaml, such as the following:

version: v1beta1build:  roots:    - proto    - vendor/googleapis

Now that workspaces are available, each of the roots can be defined as an independently configured module that can be imported by others. In the example above, the proto and vendor/googleapis roots can be defined as separate modules like so:

version: v1lint:  use:    - DEFAULTbreaking:  use:    - FILE
version: v1lint:  use:    - DEFAULTbreaking:  use:    - FILE

The workspace is defined with a, and makes it possible for users to consolidate multiple modules into a single buildable unit (just like build.roots used to do). In the example above, you can define a at the root of your VCS repository with the following:
version: v1directories:  - proto  - vendor/googleapis

With a workspace, operations like buf build, buf lint, and buf breaking can target the directory containing the file to have the same experience before they split their single buf.yaml into multiple buf.yaml files. For example, running buf lint on a directory input containing a will lint all of the modules listed in the

MINIMAL lint category#

The rules contained in the MINIMAL lint category have been slightly adjusted between v1beta1 and v1. The difference between them is shown below:

  • Removed

With these changes applied, the final result of MINIMAL is shown below:


Lint category consolidation#

Several lint categories from v1beta1 were consolidated into a smaller, more focused set. In v1, the only top-level categories are MINIMAL, BASIC, and DEFAULT. The changes are described below:

  • FILE_LAYOUT merged into MINIMAL.
  • SENSIBLE merged into BASIC.
  • STYLE_BASIC merged into BASIC.
  • STYLE_DEFAULT merged into DEFAULT.

FILE_SAME_PACKAGE breaking rule#

The FILE_SAME_PACKAGE breaking rule now belongs to the FILE, PACKAGE, WIRE_JSON, and WIRE categories. Previously, the FILE_SAME_PACKAGE rule only belonged to the FILE category, but this rule actually protects against WIRE-level compatibility because the method path can change (i.e. gRPC).

FILE_SAME_TYPE breaking rule#

The FILE_SAME_TYPE breaking rule now belongs to the FILE, PACKAGE categories. Previously, the FILE_SAME_TYPE rule also belonged to the WIRE and WIRE_JSON categories, but this rule was split into FILE_WIRE_SAME_TYPE and FILE_WIRE_JSON_SAME_TYPE to account for these levels, respectively.

Relative filepaths#

If your buf.yaml configuration file has multiple build.roots and includes build.excludes, lint.ignore[_only], or breaking.ignore[_only] values, the relative filepaths should only be copied to the new buf.yaml file that defines those files. For example, suppose that the original buf.yaml file was defined like the following:

version: v1beta1build:  roots:    - proto    - vendor/googleapis  excludes:    - acme/pet/v1/private.protolint:  ignore:    - google/type/datetime.proto  ignore_only:    ENUM_PASCAL_CASE:      - google/type/money.protobreaking:  ignore:    - acme/pet/v1/incompatible.proto  ignore_only:    FIELD_SAME_JSON_NAME:      - acme/pet/v1/store.proto

The acme/pet/v1/{incompatible,private,store}.proto files are defined in the proto root and the google/type/{datetime,money}.proto files are defined in the vendor/googleapis root. When we migrate this configuration to multiple buf.yaml files, the build.excludes, lint.ignore{_only} and breaking.ignore{_only} paths should only be migrated to the relevant buf.yaml files like so:

version: v1build:  excludes:    - acme/pet/v1/private.protobreaking:  ignore:    - acme/pet/v1/incompatible.proto  ignore_only:    FIELD_SAME_JSON_NAME:      - acme/pet/v1/store.proto
version: v1lint:  ignore:    - google/type/datetime.proto  ignore_only:    ENUM_PASCAL_CASE:      - google/type/money.proto

You'll notice that the filepath will not need to be updated because it's already relative to the module root. This transformation is automatically handled by the buf config migrate-v1beta1 command, so you don't need to worry about these nuanced details.


The buf.gen.yaml configuration file is largely unchanged, but a few changes exist for configuring Managed Mode.

Managed Mode#

Previously, users could enable Managed Mode and configure specific file options in their buf.gen.yaml like so:

version: v1beta1managed: trueoptions:  optimize_for: CODE_SIZE

The buf.gen.yaml configuration updates this so that Managed Mode and its corresponding file option overrides are encapsulated under the managed key.

version: v1managed:  enabled: true  optimize_for: CODE_SIZE

Note that managed.enabled must be set to true if any other managed overrides are set.