Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

buf-cli-lint-breaking-build

/buf-cli-lint-breaking-build

Pomaga w narzędziu buf: sprawdza lint, wykrywa zmiany łamiące kontrakt i buduje pliki protobuf, także w CI.

Repozytorium
qa ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
6
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pomaga w narzędziu buf: sprawdza lint, wykrywa zmiany łamiące kontrakt i buduje pliki protobuf, także w CI.

Oryginalny opis (EN)

Use for any question or task about the buf CLI, including adding buf to a CI workflow and reading a buf breaking or buf lint error: buf build, buf lint (STANDARD rules), buf breaking against a git or BSR baseline, buf format, and which rule category fits each consumer. Explains which changes break the wire or generated code and why. For a yes/no on one .proto diff, see protobuf-compat-checking.

Jak działa

  1. Overview
  2. When to use
  3. Authoring
  4. Running
  5. Parsing results
  6. CI integration
  7. Anti-patterns
  8. Limitations
  9. References
Sekcje z nagłówków SKILL.md, w oryginale · 216 linii, 856 słów
Podgląd SKILL.md
---
name: buf-cli-lint-breaking-build
description: "Use for any question or task about the buf CLI, including adding buf to a CI workflow and reading a buf breaking or buf lint error: buf build, buf lint (STANDARD rules), buf breaking against a git or BSR baseline, buf format, and which rule category fits each consumer. Explains which changes break the wire or generated code and why. For a yes/no on one .proto diff, see protobuf-compat-checking."
---

# buf-cli-lint-breaking-build

## Overview

Wraps three buf CLI commands - `build`, `lint`, `breaking` - as the
proto-PR gate, per
[buf.build/docs/cli/quickstart/](https://buf.build/docs/cli/quickstart/).
The catalog of what counts as breaking and why lives in
[references/versioning-strategy.md](references/versioning-strategy.md)
(+ [references/buf-breaking-rules.md](references/buf-breaking-rules.md)).

## When to use

- Adding buf as the proto lint + breaking-change gate on a new
  repo.
- A PR changes `.proto` files - need to gate the merge.
- Investigating a `buf breaking` failure - what rule fired?
- Configuring buf for a monorepo with multiple proto modules.

## Authoring

### Install

Per buf docs, install via Homebrew, Go install, or release binary.
Version 1.32.0 or higher is required. Verify:

```bash
buf --version
# 1.32.0 or higher
```

### Configure `buf.yaml`

The v2 format per
[buf.build/docs/cli/quickstart/](https://buf.build/docs/cli/quickstart/):

```yaml
version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE          # default; choose per references/versioning-strategy.md
```

`STANDARD` is the recommended lint rule set; it enforces
conventions like "Field name should be lower_snake_case" and
"Service name should be suffixed with Service".

The choice of `breaking.use` (FILE / PACKAGE / WIRE_JSON / WIRE)
follows the per-deployment-model logic in
[references/versioning-strategy.md](references/versioning-strategy.md).

### Configure `buf.gen.yaml` (codegen)

```yaml
version: v2
managed:
  enabled: true
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen
    opt: paths=source_relative
```

`managed: enabled: true` automatically sets file options without
hand-coding (e.g., `go_package`).

## Running

### Local validation pipeline

```bash
buf build && buf lint && buf breaking --against ".git#branch=main"
```

Three gates in order: compile, lint, breaking. All three must
pass before merge.

### `buf build`

```bash
buf build
# Silent exit on success
```

Compiles every `.proto` in the workspace. Silent → success. Any
output → error. Equivalent to `protoc` compilation but reads
`buf.yaml` for paths.

### `buf lint`

```bash
buf lint
# Emits violations as: <file>:<line>:<col>:<msg>
```

Validates against the configured rule set. Common failures:

| Failure | Rule | Fix |
|---|---|---|
| `Field name "userId" should be lower_snake_case` | `FIELD_LOWER_SNAKE_CASE` | Rename to `user_id` |
| `Service "Users" should be suffixed with "Service"` | `SERVICE_SUFFIX` | Rename to `UsersService` |
| `Message "user_data" should be UpperCamelCase` | `MESSAGE_UPPER_CAMEL_CASE` | Rename to `UserData` |
| `Enum value should be SCREAMING_SNAKE_CASE` | `ENUM_VALUE_UPPER_SNAKE_CASE` | Rename |

### `buf breaking`

```bash
buf breaking --against ".git#branch=main"
# Compares working tree against main branch
```

Baselines (per [buf docs](https://buf.build/docs/cli/quickstart/)):

| Baseline | Use |
|---|---|
| `".git#branch=main"` | Compare against main branch (CI default) |
| `".git#tag=v1.0.0"` | Compare against a release tag |
| `".git#subdir=path/to/proto"` | Sub-directory baseline (monorepo) |
| `"path/to/image.bin"` | Pre-built `buf build` image file |
| `"buf.build/owner/module"` | Compare against published BSR image |

Output on violation:

```
proto/foo.proto:42:5: Field "old_name" with type "string" no longer exists (rule FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED).
```

Per [buf breaking rules](https://buf.build/docs/breaking/rules):
each violation cites the rule that fired so you know which
category constraint was violated.

## Parsing results

### CLI output (text, default)

Each violation: `<file>:<line>:<col>: <message> (rule <RULE_ID>).`

Pipe to grep / awk for counts:

```bash
buf breaking --against ".git#branch=main" 2>&1 | tee buf-breaking.log
wc -l buf-breaking.log
```

### Machine-readable output

```bash
buf lint --error-format=json
# Emits: [{"path":"...","start_line":...,"start_col":...,"end_line":...,"type":"FIELD_LOWER_SNAKE_CASE","message":"..."}]

buf breaking --against ".git#branch=main" --error-format=json
```

For consumption by a unified reporter.

## CI integration

Gate `buf build` / `lint` / `breaking` on PRs that touch `.proto`,
`buf.yaml`, or `buf.gen.yaml`. Key gotcha: `fetch-depth: 0` so git
has the baseline commit available. Full GitHub Actions workflow plus
the failure PR-comment:
[references/ci-integration.md](references/ci-integration.md).

## Anti-patterns

| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Skipping `buf breaking` on PR | Subtle wire breakage merges; consumers crash at deploy time | Always gate; never `--ignore` blanket |
| Comparing against the PR's own merge base | Self-baseline; no detection | Use `".git#branch=main"` |
| `fetch-depth: 1` in CI | git can't reach baseline → buf errors | `fetch-depth: 0` |
| `breaking.use: WIRE` for codegen consumers | Generated code break (rename) passes; consumer build fails | Use `FILE` or `PACKAGE` per references/versioning-strategy.md |
| Adding `--ignore` to suppress a real violation | Silent regression | Use proper reserved + deprecation instead |
| Lint set `MINIMAL` for new projects | Misses snake_case + service-suffix conventions early | Use `STANDARD` from day 1 |
| One `buf.yaml` per proto file | Doesn't compose; lint runs N times | One `buf.yaml` at module root |
| Inconsistent baselines (main vs tag) | Different reviewers see different verdicts | Pick one CI baseline; document |

## Limitations

- **Semantic vs wire breakage.** Per
  [references/versioning-strategy.md](references/versioning-strategy.md),
  buf detects binary/codegen breakage. Semantic meaning changes
  ("field now means net price, not gross") are undetectable.
- **No cross-service compatibility.** This is single-service
  schema lint. For service-to-service contract testing see
  `protobuf-compat-checking`.
- **BSR features require auth.** Remote plugins, registry pushes,
  and `buf.build/...` baselines need a BSR account.
- **JSON-name detection** is in WIRE_JSON only. Services that
  use only binary won't see JSON name changes detected.
- **Doesn't generate code automatically.** `buf generate` is a
  separate step; this skill scopes to gating.

## References

- buf CLI quickstart:
  [buf.build/docs/cli/quickstart/](https://buf.build/docs/cli/quickstart/).
- buf breaking rules:
  [buf.build/docs/breaking/rules](https://buf.build/docs/breaking/rules).
- Versioning + breaking-change catalog:
  [references/versioning-strategy.md](references/versioning-strategy.md)
  (+ [references/buf-breaking-rules.md](references/buf-breaking-rules.md)).
- Status code vocabulary:
  `grpc-streaming-test-author` (references/status-codes.md).
- Sibling tools:
  `ghz-load`,
  `grpcurl-cli`,
  `grpc-mock`.
- Cross-service contract testing:
  `protobuf-compat-checking`.
Pliki w paczce (5)
  • SKILL.md 7 KB
  • .tessl-plugin/plugin.json 1 KB
  • references/buf-breaking-rules.md 2 KB
  • references/ci-integration.md 2 KB
  • references/versioning-strategy.md 8 KB

Wersje

W bazie nie ma innych skilli o nazwie buf-cli-lint-breaking-build.

Migawka bazy z 13.11.2026 · wersja paczki 7dedf557acae (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100protobuf-compat-checking
    Opakowuje buf breaking, aby porównać schemat Protobuf z wcześniejszą wersją, klasyfikuje zmiany łamiące zgodność (FILE, PACKAGE, WIRE_JSON, WIRE), konfiguruje reguły w buf.yaml i blokuje CI według kodu wyjścia.
  • 100protobuf
    Obsługuje pliki Protocol Buffer (.proto), buf.yaml, buf.gen.yaml i buf.lock: projekt proto, CLI buf, usługi gRPC i Connect, ograniczenia protovalidate, ewolucja schematu oraz błędy lint i breaking.
  • 100review-api-compat
    Sprawdza zgodność wsteczną API: zmiany łamiące w proto, buf breaking, OpenAPI i gRPC oraz ewolucję kontraktu.
  • 100protobuf-evolve-schemas
    Rozwija istniejący schemat protobuf bez łamania konsumentów: zmiany nazw pól i typów, zarezerwowane numery i nazwy, wykrywanie zmian łamiących w CI przez buf breaking oraz wersjonowanie pakietów.
  • 100protobuf-dev
    Zapewnia wiedzę o programowaniu w Protocol Buffers: wytyczne stylu, zgodność wsteczna, wzorce projektowe i wykrywanie systemu budowania (buf, Bazel) przy tworzeniu i przeglądzie plików .proto.
  • 100review-code
    Przegląda kod i architekturę w Go: dobre praktyki, protobuf, projekt API, SOLID, wzorce, sprzężenie i spójność, testowalność oraz gocyclo, staticcheck i buf lint.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.