Skip to content

Commit ae3ac05

Browse files
authored
hack: reject breaking proto changes across each proto package (agent-substrate#1607)
ateapi stores resources as binary protobuf in `bytea` columns. Binary protobuf identifies a field only by its number. If a field is renumbered, existing rows lose its value. If a retired number is reused, existing rows decode into the wrong field. `atepg.go` unmarshals with `DiscardUnknown: true`, so the original bytes are dropped on the next read-modify-write. Nothing reports this at runtime. - `hack/tools/buf`: adds buf v1.72.0 as a tool module, run through `hack/run-tool.sh`. - `buf.yaml`: checks the protos under `api/`, `internal/proto/`, and `pkg/proto/` with buf's `PACKAGE` breaking rules. Within a proto package, declarations may move between `.proto` files, but messages, enums, services, RPCs, fields, enum values, and reserved ranges cannot be deleted, renamed, renumbered, or retyped. - `hack/verify/proto-breaking.sh`: runs `buf breaking` on the working tree against the merge base of `HEAD` and `origin/main` (or `main`). CI checks out with `fetch-depth: 0`, so the merge base is available there. It passes `--against-config buf.yaml` so a baseline commit without `buf.yaml` still builds. - `AGENTS.md`: removes the Backward Compatibility section. Breaking changes are no longer acceptable once this check is in. - `hack/verify-all.sh`: runs every verifier and lists the failures at the end, instead of stopping at the first one. This is to make sure the CI runs every verifier on a PR including breaking proto changes. I can split this into its own PR if you prefer. I used Claude Code to help write the change and this description. --------- Signed-off-by: Haiyan Meng <[email protected]>
1 parent 671cb69 commit ae3ac05

6 files changed

Lines changed: 433 additions & 10 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
- Comment the final state of the code. Bugs that only existed while you were writing the change, and links to planning docs outside the repository, are noise to the next reader.
4646
- Check every claim in comments, docs and the PR description against the code. Don't claim a guarantee the code doesn't enforce. When you change behavior, update the comments, docs and scripts elsewhere that describe it. Link to existing docs instead of copying them.
4747
- Find the root cause before fixing a symptom. Back performance claims with a measurement.
48-
- Keep atelet and the worker runtimes opaque to each other. The only knowledge they may share is `internal/proto/ateworkerpb` and the paths in `internal/nodepath`. Using the same library code is fine; depending on how the other side is built is not. We want atelet to roll ahead of workers eventually, so don't widen that interface casually. Until v1.0.0 nothing enforces this; see Backward Compatibility.
48+
- Keep atelet and the worker runtimes opaque to each other. The only knowledge they may share is `internal/proto/ateworkerpb` and the paths in `internal/nodepath`. Using the same library code is fine; depending on how the other side is built is not. We want atelet to roll ahead of workers eventually, so don't widen that interface casually.
4949
- Actor features work on both gVisor and microVM, with e2e coverage for both, unless the issue or PR description scopes the change to one runtime.
5050
- Don't assume kind, GKE, amd64 or a newer kernel than the repo already needs. Dev scripts must work on arm64 macOS. Don't change host-wide state.
5151
- Put shell code in standalone `.sh` scripts so shellcheck can lint them. Place each script near what uses it, such as `hack/` for dev scripts or a directory under `.github/` for a workflow. Don't inline it in YAML, such as a GitHub workflow `run:` block, in JSON, or in another language's source, such as Go or Python. Have those call the script. Get a reviewer's agreement before making an exception.
@@ -122,14 +122,6 @@ The dev entry points are the scripts under `hack/` and the `cmd/ate-setup` insta
122122
- **Go Modules**: Ensure `go.mod` is clean. Run `go mod tidy` if adding or removing dependencies.
123123
- **Spelling**: American English. `golangci-lint` runs `misspell` with `locale: US`, so British spellings fail lint.
124124

125-
## Backward Compatibility
126-
127-
<!-- TODO #2004: Remove this section at the v1.0.0 release. -->
128-
129-
Agent Substrate makes no compatibility guarantee before v1.0.0. Do not add code to stay compatible with older clients, binaries, protos, flags, or config.
130-
Remove or rename fields, RPCs, flags, and types outright and update every caller in the same change.
131-
Do not add `reserved` statements to protos, deprecated aliases, fallbacks for old formats, or version negotiation.
132-
133125
## Version Skew
134126

135127
From v1.0.0, changes must keep upgrades and rollbacks working under [docs/reference/version-skew-policy.md](docs/reference/version-skew-policy.md). Read it before you change an RPC, a CRD, the worker pod template, a database migration, or file(s) that `atelet` and `ateworker` share on a node.

‎buf.yaml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
version: v2
16+
17+
# See hack/verify/proto-breaking.sh.
18+
modules:
19+
- path: .
20+
includes:
21+
- api
22+
- internal/proto
23+
- pkg/proto
24+
25+
breaking:
26+
use:
27+
- PACKAGE

‎hack/tools/buf/go.mod‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
module go.ate.dev/substrate/hack/tools/buf
2+
3+
go 1.27.0
4+
5+
toolchain go1.27.3
6+
7+
tool github.com/bufbuild/buf/cmd/buf
8+
9+
require (
10+
buf.build/gen/go/bufbuild/bufplugin/protocolbuffers/go v1.36.11-20260626152828-968bf0468096.1 // indirect
11+
buf.build/gen/go/bufbuild/protodescriptor/protocolbuffers/go v1.36.11-20250109164928-1da0de137947.1 // indirect
12+
buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go v1.36.11-20260709200747-435963d16310.1 // indirect
13+
buf.build/gen/go/bufbuild/registry/connectrpc/go v1.20.0-20260713175918-10d915f5b43b.1 // indirect
14+
buf.build/gen/go/bufbuild/registry/protocolbuffers/go v1.36.11-20260713175918-10d915f5b43b.1 // indirect
15+
buf.build/gen/go/pluginrpc/pluginrpc/protocolbuffers/go v1.36.11-20241007202033-cf42259fcbfc.1 // indirect
16+
buf.build/go/app v0.2.1-0.20260626143626-be153867abea // indirect
17+
buf.build/go/bufplugin v0.10.0 // indirect
18+
buf.build/go/bufprivateusage v0.1.0 // indirect
19+
buf.build/go/interrupt v1.1.0 // indirect
20+
buf.build/go/protovalidate v1.2.0 // indirect
21+
buf.build/go/protoyaml v0.7.0 // indirect
22+
buf.build/go/spdx v0.2.0 // indirect
23+
buf.build/go/standard v0.1.1-0.20260325175353-2b287e071df5 // indirect
24+
cel.dev/expr v0.25.2 // indirect
25+
connectrpc.com/connect v1.20.0 // indirect
26+
connectrpc.com/otelconnect v0.9.0 // indirect
27+
github.com/Microsoft/go-winio v0.6.2 // indirect
28+
github.com/antlr4-go/antlr/v4 v4.13.1 // indirect
29+
github.com/bufbuild/buf v1.72.0 // indirect
30+
github.com/bufbuild/protocompile v0.14.2-0.20260716165721-bb5762d29672 // indirect
31+
github.com/bufbuild/protoplugin v0.0.0-20260414125817-25d1d281b46b // indirect
32+
github.com/cespare/xxhash/v2 v2.3.0 // indirect
33+
github.com/cli/browser v1.3.0 // indirect
34+
github.com/containerd/errdefs v1.0.0 // indirect
35+
github.com/containerd/errdefs/pkg v0.3.0 // indirect
36+
github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
37+
github.com/distribution/reference v0.6.0 // indirect
38+
github.com/docker/cli v29.6.1+incompatible // indirect
39+
github.com/docker/docker-credential-helpers v0.9.8 // indirect
40+
github.com/docker/go-connections v0.7.0 // indirect
41+
github.com/docker/go-units v0.5.0 // indirect
42+
github.com/felixge/httpsnoop v1.1.0 // indirect
43+
github.com/go-logr/logr v1.4.3 // indirect
44+
github.com/go-logr/stdr v1.2.2 // indirect
45+
github.com/gofrs/flock v0.13.0 // indirect
46+
github.com/google/cel-go v0.29.2 // indirect
47+
github.com/google/go-containerregistry v0.21.7 // indirect
48+
github.com/google/uuid v1.6.0 // indirect
49+
github.com/inconshreveable/mousetrap v1.1.0 // indirect
50+
github.com/jdx/go-netrc v1.0.0 // indirect
51+
github.com/klauspost/compress v1.19.0 // indirect
52+
github.com/klauspost/pgzip v1.2.6 // indirect
53+
github.com/mattn/go-colorable v0.1.15 // indirect
54+
github.com/mattn/go-isatty v0.0.23 // indirect
55+
github.com/moby/docker-image-spec v1.3.1 // indirect
56+
github.com/moby/moby/api v1.55.0 // indirect
57+
github.com/moby/moby/client v0.5.0 // indirect
58+
github.com/opencontainers/go-digest v1.0.0 // indirect
59+
github.com/opencontainers/image-spec v1.1.1 // indirect
60+
github.com/petermattis/goid v0.0.0-20260716134002-a9b348f0a2b9 // indirect
61+
github.com/quic-go/qpack v0.6.0 // indirect
62+
github.com/quic-go/quic-go v0.60.0 // indirect
63+
github.com/rivo/uniseg v0.4.7 // indirect
64+
github.com/rs/cors v1.11.1 // indirect
65+
github.com/russross/blackfriday/v2 v2.1.0 // indirect
66+
github.com/segmentio/asm v1.2.1 // indirect
67+
github.com/segmentio/encoding v0.5.4 // indirect
68+
github.com/sirupsen/logrus v1.9.4 // indirect
69+
github.com/spf13/cobra v1.10.2 // indirect
70+
github.com/spf13/pflag v1.0.10 // indirect
71+
github.com/tetratelabs/wazero v1.12.0 // indirect
72+
github.com/tidwall/btree v1.8.1 // indirect
73+
go.lsp.dev/jsonrpc2 v0.10.0 // indirect
74+
go.lsp.dev/pkg v0.0.0-20210717090340-384b27a52fb2 // indirect
75+
go.lsp.dev/protocol v0.12.0 // indirect
76+
go.lsp.dev/uri v0.3.0 // indirect
77+
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
78+
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 // indirect
79+
go.opentelemetry.io/otel v1.44.0 // indirect
80+
go.opentelemetry.io/otel/metric v1.44.0 // indirect
81+
go.opentelemetry.io/otel/trace v1.44.0 // indirect
82+
go.uber.org/multierr v1.11.0 // indirect
83+
go.uber.org/zap v1.28.0 // indirect
84+
go.yaml.in/yaml/v3 v3.0.4 // indirect
85+
golang.org/x/crypto v0.54.0 // indirect
86+
golang.org/x/exp v0.0.0-20260709172345-9ea1abe57597 // indirect
87+
golang.org/x/mod v0.38.0 // indirect
88+
golang.org/x/net v0.57.0 // indirect
89+
golang.org/x/sync v0.22.0 // indirect
90+
golang.org/x/sys v0.47.0 // indirect
91+
golang.org/x/term v0.45.0 // indirect
92+
golang.org/x/text v0.40.0 // indirect
93+
google.golang.org/genproto/googleapis/api v0.0.0-20260715232425-e75dac1f907d // indirect
94+
google.golang.org/genproto/googleapis/rpc v0.0.0-20260715232425-e75dac1f907d // indirect
95+
google.golang.org/protobuf v1.36.11 // indirect
96+
gopkg.in/yaml.v3 v3.0.1 // indirect
97+
mvdan.cc/xurls/v2 v2.6.0 // indirect
98+
pluginrpc.com/pluginrpc v0.5.0 // indirect
99+
)

0 commit comments

Comments
 (0)