workspace

Buf workspace example

Note

You need to have the buf CLI installed to follow along with this example.

This directory provides an example of a Buf workspace that contains multiple Buf modules that are meant to be consumed as dependencies by other Protobuf projects. There are two modules in this workspace:

• observabilityapi defines an observability-related service.
• observabilitytypes defines many of the types used by the service in the observabilityapi module.

Both modules are available on the Buf Schema Registry:

• buf.build/buf-examples/observabilityapi
• buf.build/buf-examples/observabilitytypes

Structure

The basic structure of this workspace:

.
├── buf.gen.yaml
├── buf.yaml
├── observabilityapi
│   ├── api
│   │   ├── v1
│   │   │   └── api.proto
│   │   └── v2
│   │       └── api.proto
└── observabilitytypes
    ├── log
    │   ├── v1
    │   │   └── log.proto
    │   ├── v2
    │   │   └── log.proto
    │   └── v3
    │       └── log.proto
    └── metric
        └── v1
            └── metric.proto

The workspace configuration is defined in buf.yaml.

Linting

To lint all of the Buf modules in the workspace:

buf lint

To lint specific modules:

buf lint observabilityapi
buf lint observabilitytypes

Breaking change detection

To perform breaking change detection against the previous commit to the main branch of this repository:

buf breaking \
--against ../.git#branch=main,ref=HEAD~1,subdir=workspace

As with buf lint, buf breaking detects breaking changes amongst all modules. To target only a specific module:

buf breaking observabilitytypes \
--against ../.git#branch=main,ref=HEAD~1,subdir=workspace

In this case, the --against flag targets the root of this repository using ../.git and then this directory using subdir=workspace. In most projects, you would likely be able to use a more straightforward target, like this:

buf breaking observabilitytypes \
--against .git#branch=main,ref=HEAD~1

Code generation

To generate code stubs for all modules in the workspace using the plugins defined in buf.gen.yaml:

buf generate

To generate code stubs for specific modules:

buf generate observabilityapi
buf generate observabilitytypes