Several changes were made between v1beta1
and v1
, but migrating between them should be straightforward. This guide
walks you through exactly what changed and what you need to update when upgrading from v1beta1
to v1
.
Automatic migration
The buf beta migrate-v1beta1
command automatically migrates all of your buf
configuration files from v1beta1
to
v1
.
For example, consider this buf.yaml
with multiple roots:
version: v1beta1
build:
roots:
- proto
- vendor/googleapis
breaking:
use:
- FILE
lint:
use:
- DEFAULT
.
├── 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 beta migrate-v1beta1
in a
directory containing a buf.yaml
, buf.lock
, or buf.gen.yaml
:
$ buf beta migrate-v1beta1
OutputSuccessfully 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
buf.work.yaml
was created:
.
├── buf.gen.yaml
├── buf.work.yaml
├── proto
│ ├── acme
│ │ └── pet
│ │ └── v1
│ │ └── pet.proto
│ ├── buf.lock
│ └── buf.yaml
└── vendor
└── googleapis
├── buf.lock
├── buf.yaml
└── google
└── type
└── datetime.proto
The sections below explain what changed between v1beta1
and v1
in more detail.
buf.yaml
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.
build.roots
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 this:
version: v1beta1
build:
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, as in these configurations:
version: v1
breaking:
use:
- FILE
lint:
use:
- DEFAULT
version: v1
breaking:
use:
- FILE
lint:
use:
- DEFAULT
The workspace is defined with a buf.work.yaml
, 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 buf.work.yaml
at the root of your VCS repository with this:
version: v1
directories:
- proto
- vendor/googleapis
With a workspace, operations like buf build
, buf lint
, and buf breaking
can target the directory containing the
buf.work.yaml
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 buf.work.yaml
lints
all of the modules listed in the buf.work.yaml
.
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
ENUM_NO_ALLOW_ALIAS
FIELD_NO_DESCRIPTOR
IMPORT_NO_PUBLIC
IMPORT_NO_WEAK
PACKAGE_SAME_CSHARP_NAMESPACE
PACKAGE_SAME_GO_PACKAGE
PACKAGE_SAME_JAVA_MULTIPLE_FILES
PACKAGE_SAME_JAVA_PACKAGE
PACKAGE_SAME_PHP_NAMESPACE
PACKAGE_SAME_RUBY_PACKAGE
PACKAGE_SAME_SWIFT_PREFIX
With these changes applied, the final result of MINIMAL
is shown below:
DIRECTORY_SAME_PACKAGE
PACKAGE_DEFINED
PACKAGE_DIRECTORY_MATCH
PACKAGE_SAME_DIRECTORY
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 intoMINIMAL
.PACKAGE_AFFINITY
merged intoBASIC
.SENSIBLE
merged intoBASIC
.STYLE_BASIC
merged intoBASIC
.STYLE_DEFAULT
merged intoDEFAULT
.
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 (as often happens with gRPC, for example).
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 this:
version: v1beta1
build:
roots:
- proto
- vendor/googleapis
excludes:
- acme/pet/v1/private.proto
lint:
ignore:
- google/type/datetime.proto
ignore_only:
ENUM_PASCAL_CASE:
- google/type/money.proto
breaking:
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, as in these configurations:
version: v1
build:
excludes:
- acme/pet/v1/private.proto
breaking:
ignore:
- acme/pet/v1/incompatible.proto
ignore_only:
FIELD_SAME_JSON_NAME:
- acme/pet/v1/store.proto
version: v1
lint:
ignore:
- google/type/datetime.proto
ignore_only:
ENUM_PASCAL_CASE:
- google/type/money.proto
You'll notice that the filepath doesn't need to be updated because it's already relative to the module root. This
transformation is automatically handled by the buf beta migrate-v1beta1
command, so you don't need to worry about
these nuanced details.
buf.gen.yaml
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 this:
version: v1beta1
managed: true
options:
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: v1
managed:
enabled: true
optimize_for: CODE_SIZE
Note that managed.enabled
must be set to true
if any other managed
overrides are set.