<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Label this issue](https://contributors.gitlab.com/manage-issue?action=label&projectId=278964&issueIid=604561) - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=604561) </details> <!--IssueSummary end--> ## Introduction GitLab is moving towards using shared protocol buffer definitions as interfaces. Many projects at GitLab already provide protobuf definitions, including: 1. https://gitlab.com/gitlab-org/gitaly/-/tree/master/proto 2. https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/main/crates/gkg-server/proto/gkg.proto 3. https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/tree/main/clients/gopb 4. https://gitlab.com/gitlab-org/analytics-section/siphon/-/blob/main/clients/rust/siphon-proto Additionally, LabKit now mandates that all configuration for modules is expressed with a protobuf schema: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/labkit_configuration/ ## Challenges One of the challenges raised by the Auth team was around sharing protobuf client libraries between modules. Having a consistent means of doing this allows team to quickly and easily publish and consume protobufs, without having to facilitate inter-team communications for each change to each module. With this in mind, a shared piece of development infrastructure was proposed: the Protos Monorepo. The details of this approach are documented below. cc @skodali3 @e_forbes @mkaeppler @skundapur @jdrpereira @ash2k ## Goals 1. One monorepo at **`gitlab-org/protos`** (`gitlab.com/gitlab-org/protos`) eventually holding all GitLab protobuf definitions. 2. Two source kinds, side by side: - **Vendored** — pulled from upstream repos via **Vendir**, kept up to date by **Renovate**, living under `/vendor`. - **Direct** — authored and committed in-repo. 3. **The split must be invisible to clients.** Moving a package from vendored → direct (or back) must require *zero* changes in any generated client. Physical location is an implementation detail. 4. Generate **Ruby, Rust, Go, Python** packages. Generated **source is committed**. 5. One **consistent build system**. 6. **No needless rebuilds** — if a package's schema didn't change, downstream consumers shouldn't have to recompile or re-resolve it. --- ## Repository layout ``` protos/ # gitlab.com/gitlab-org/protos ├── buf.yaml # workspace: lists every module (direct + vendored) ├── buf.gen.yaml # codegen config (managed mode + plugins + inputs) ├── buf.lock # pinned BSR deps (e.g. googleapis, protovalidate) ├── vendir.yml # declares vendored upstream sources ├── vendir.lock.yml # resolved commits (written by `vendir sync`) ├── renovate.json # auto-update config for vendored sources ├── Taskfile.yml # the one build entrypoint │ ├── proto/ # DIRECT, committed-in-repo protobufs │ └── gitlab/ │ └── foo/v1/foo.proto # package gitlab.foo.v1; -> import "gitlab/foo/v1/foo.proto" │ ├── vendor/ # VENDORED sources (managed by vendir, do not hand-edit) │ ├── gitaly/ │ │ └── gitaly/v1/*.proto # package gitaly.v1; -> import "gitaly/v1/blob.proto" │ └── some-upstream/ │ └── ... │ └── gen/ # GENERATED SOURCE — committed ├── go/ ├── ruby/ ├── python/ └── rust/ ``` Two structural rules: - **`vendor/` is the *only* thing that distinguishes vendored from direct.** Nothing in `gen/`, in client import paths, or in package names references it. - **Beneath each module root, the path equals the proto package.** `vendor/gitaly` is a module root; under it, `gitaly/v1/...` mirrors `package gitaly.v1`. That alignment is what keeps import paths stable across a move. --- ## The buf workspace The monorepo relies on buf to managing, validatings and generating based on protobuf definitions. ### `buf.yaml` ```yaml version: v2 # Every module — vendored and direct — is listed here. # `path` is where the files live; it has no effect on import paths. modules: - path: proto - path: vendor/gitaly # Per-module overrides fully REPLACE workspace defaults (they don't merge). # Vendored code we don't own: relax lint, keep breaking strict. lint: use: [MINIMAL] breaking: use: [FILE] - path: vendor/some-upstream lint: use: [MINIMAL] # Workspace-wide defaults for modules that don't override them. lint: use: [STANDARD] breaking: use: [FILE] # External well-known protos. NOTE: pulling these from the public BSR is the one # remaining BSR touchpoint. To be fully BSR-free, vendor them via vendir into # /vendor and declare them as modules above instead of listing them here. deps: - buf.build/googleapis/googleapis - buf.build/bufbuild/protovalidate ``` Notes: - Modules in the same workspace import each other with **no `deps` entry** — the local resolver sees them first. So a direct proto can `import "gitaly/v1/blob.proto"` whether `gitaly` is vendored or direct. - `deps` here pull external well-known types from the public BSR (pinned in `buf.lock` via `buf dep update`). **This is the only place the design touches BSR.** If "avoid BSR" is meant strictly, vendor googleapis/protovalidate via vendir like any other upstream and drop both `deps` and `buf.lock` — at the cost of a little more vendir maintenance. ### Promoting / demoting a module (the key workflow) To **promote** `gitaly` from vendored to directly-committed: 1. `git mv vendor/gitaly/gitaly proto/gitaly` — the package sub-path (`gitaly/v1/...`) is preserved. 2. In `buf.yaml`, delete the `vendor/gitaly` module (it now lives under the `proto` root) **or** repoint its `path` to `proto/gitaly` if you want to keep it as its own module. 3. Remove the `gitaly` entry from `vendir.yml`. 4. `buf generate`. Result: import path `gitaly/v1/blob.proto` is unchanged, every generated package name is unchanged, and `buf generate` produces **byte-identical** output — so `git diff gen/` is empty. No client changes, no version bumps, no rebuilds. Demotion (direct → vendored) is the same in reverse. The reason this works: nothing downstream ever encoded the `vendor/` prefix. Import paths and generated names came from the proto `package` + managed mode, both location-independent. --- ## Code generation ### `buf.gen.yaml` ```yaml version: v2 # Managed mode sets language options at generation time so they don't have to be # hand-written into every .proto — and so they're derived from the package, not the path. managed: enabled: true override: # Go import paths: <prefix>/<proto package path>. Location-independent. - file_option: go_package_prefix value: gitlab.com/gitlab-org/protos/gen/go disable: # Don't rewrite go_package for well-known external modules. - module: buf.build/googleapis/googleapis file_option: go_package_prefix plugins: # --- Go --- - remote: buf.build/protocolbuffers/go:vX.Y.Z # pin to a real, current version out: gen/go opt: paths=source_relative - remote: buf.build/grpc/go:vX.Y.Z out: gen/go opt: paths=source_relative # --- Python (messages + grpc + type stubs) --- - remote: buf.build/protocolbuffers/python:vX.Y.Z out: gen/python - remote: buf.build/protocolbuffers/pyi:vX.Y.Z out: gen/python - remote: buf.build/grpc/python:vX.Y.Z out: gen/python # --- Ruby --- - remote: buf.build/protocolbuffers/ruby:vX.Y.Z out: gen/ruby - remote: buf.build/grpc/ruby:vX.Y.Z out: gen/ruby # --- Rust (community plugins; first-party Rust support does not exist) --- - remote: buf.build/community/neoeinstein-prost:vX.Y.Z out: gen/rust/src - remote: buf.build/community/neoeinstein-tonic:vX.Y.Z out: gen/rust/src # neoeinstein-prost-crate emits a mod tree + features wiring suitable for a crate. # v2 lets the input live here, so `buf generate` needs no wrapper flags. inputs: - directory: . # the whole workspace = every module, vendored and direct ``` Decisions baked in here: - **Remote plugins, version-pinned.** No local `protoc`/plugin installs; everyone (and CI) runs identical plugin versions. The trade-off is a network dependency at generation time. If you need offline/air-gapped generation, switch the same entries to `local:` plugins pinned via `mise`/asdf. Pick one and keep it consistent — that's requirement #5. - **Rust is the rough edge.** There is no first-party buf Rust plugin; `neoeinstein-prost` / `neoeinstein-tonic` (and `-prost-crate`) are the de-facto standard. Pin them carefully and treat Rust output as the one to validate most. --- ## Vendoring + automated updates ### `vendir.yml` ```yaml apiVersion: vendir.k14s.io/v1alpha1 kind: Config minimumRequiredVersion: 0.40.0 directories: - path: vendor/gitaly contents: - path: . git: url: https://gitlab.com/gitlab-org/gitaly.git ref: v17.5.0 # <- Renovate bumps this includePaths: - proto/**/*.proto # only pull the protos # Reshape so that, under vendor/gitaly, the tree starts at the proto package path. # The exact value depends on each upstream's layout. The TARGET is always: # vendor/<name>/<proto-package-path>/x.proto newRootPath: proto ``` After `vendir sync`, files land at `vendor/<name>/<proto-package-path>/…` so the buf module root (`vendor/<name>`) yields the correct, stable import path. Tune `includePaths` / `excludePaths` / `newRootPath` per upstream. `vendir sync` writes `vendir.lock.yml` with the resolved commit SHAs — commit it for reproducibility. ### `renovate.json` Renovate now ships a **native `vendir` manager** (matches `vendir.yml`), so you don't need a hand-rolled regex manager for git-ref and release bumps: ```json { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["config:recommended"], "vendir": { "managerFilePatterns": ["/(^|/)vendir\\.ya?ml$/"] }, "packageRules": [ { "matchManagers": ["vendir"], "groupName": "vendored protobuf sources", "commitMessageTopic": "vendored proto {{depName}}", "schedule": ["before 6am on monday"] } ], "postUpgradeTasks": { "commands": ["vendir sync", "task generate"], "fileFilters": ["vendor/**", "vendir.lock.yml", "gen/**"], "executionMode": "branch" } } ``` ### Keeping synced sources + generated code consistent Renovate only edits the **ref in `vendir.yml`** — it does not run `vendir sync` or regenerate. You need that to happen so the MR carries the synced `vendor/` tree, the updated `vendir.lock.yml`, and the regenerated `gen/`. Two ways: - **`postUpgradeTasks` (shown above).** Clean, but requires *self-hosted* Renovate with these commands allow-listed (`allowedPostUpgradeCommands`). - **A CI job on the Renovate branch (recommended if you're on hosted/Mend Renovate).** When `vendir.yml` changes, CI runs `vendir sync && task generate` and commits the result back to the MR. Platform-agnostic; no special Renovate trust needed. Either way the rule is: **a vendored ref bump and its regenerated output land in the same MR.** Breaking-change detection (below) then gates it. --- ## Build system & incrementality ### Determinism `buf generate` is deterministic: identical proto inputs + pinned plugins ⇒ **byte-identical** generated source. Because the source is committed, the cheapest, most trustworthy "did anything change?" signal is **git itself**. So the model is: 1. `vendir sync` (only if vendored refs changed) 2. `buf generate` (regenerate everything — it's fast and deterministic) 3. If `git diff gen/` is empty → nothing changed, stop. 4. Otherwise, only the modules whose generated tree changed get a version bump + publish. This is what satisfies "no recompile when no changes": unchanged modules produce no diff → no version bump → consumers' lockfiles don't move → nothing downstream rebuilds. ### Orchestration: Taskfile Starting simple: tool provisioning and task running are kept separate and lightweight, with a clear path to grow into a content-hashing build system later. **Tools** are pinned in `.tool-versions` (GitLab convention; asdf format, also read natively by mise), so a fresh checkout is one `mise install` (or `asdf install`) from a working environment: ``` # .tool-versions buf <pinned> vendir <pinned> go <pinned> rust <pinned> # cargo/rustc toolchain python <pinned> uv <pinned> ruby <pinned> ``` **Tasks** run through [go-task]: a single static binary, language-agnostic, whose `method: checksum` skips a task when its declared input checksums are unchanged. One `Taskfile.yml` is the entrypoint: ```yaml version: '3' tasks: default: cmds: [{ task: generate }] vendir-sync: cmds: [vendir sync] sources: [vendir.yml] generates: [vendir.lock.yml] method: checksum generate: deps: [vendir-sync] cmds: - buf generate - ./scripts/gen-manifests.sh # template Cargo.toml / pyproject.toml / *.gemspec from the module list sources: - 'proto/**/*.proto' - 'vendor/**/*.proto' - buf.yaml - buf.gen.yaml # pinned plugin versions → part of the checksum - buf.lock - 'scripts/manifest-templates/**' generates: ['gen/**/*'] method: checksum # skipped entirely when no proto/config changed lint: cmds: [buf lint] breaking: cmds: ["buf breaking --against '.git#tag=last-release'"] ``` `generate` short-circuits when nothing changed. Taskfile has no built-in "affected" detection, so when the publish overlays are enabled, a small `git diff` against the merge base identifies which `gen/<lang>/<module>` trees changed and therefore which packages to publish — adequate at this scale. Note that generation should be fast: - **Go & Rust** have content-addressed build caches (Go build cache; Cargo fingerprints). Even inside a monolithic package, a consumer only recompiles compilation units whose *content* changed. Deterministic generation guarantees unchanged files are byte-identical, so the cache hits stand. These two are forgiving by nature. - **Ruby & Python** have no compile step, so "recompile" really means "reinstall / republish." The lever there is **package granularity**: keep unchanged modules at the same published version so consumer lockfiles don't churn. --- ## Packaging per language Recommendation: **one package per proto module, per language** (granular), for clean dependency graphs. Since consumers pull these straight from git (see below), the cost of granularity is just a per-module manifest committed in each output dir — there is no publish matrix to operate. These manifests are **generated, not hand-maintained** (decided): a templating step in the codegen task emits each module's manifest from the buf module list plus managed naming, so adding a proto module never does not mean hand-writing four manifests. In practice the Rust crate manifest can come straight from the `neoeinstein-prost-crate` plugin; the `pyproject.toml` and `*.gemspec` are small per-module templates keyed off the module name and managed package name; and Go needs only the single near-static `gen/go/go.mod`. Inter-crate Rust deps are plain `path` deps within the workspace (no registry version needed while git-sourced). | Language | Plugin(s) | Committed manifest | Consumed from git as | |----------|---------------------------------------------|-------------------------|----------------------| | Go | `protocolbuffers/go`, `grpc/go` | `gen/go/go.mod` | `go get gitlab.com/gitlab-org/protos/gen/go@gen/go/vX.Y.Z` | | Rust | `neoeinstein-prost`, `neoeinstein-tonic` | `Cargo.toml` per crate | `{ git = "…/protos.git", tag = "…", package = "<crate>" }` | | Ruby | `protocolbuffers/ruby`, `grpc/ruby` | `*.gemspec` per module | `gem "<name>", git: "…/protos.git", glob: "gen/ruby/<m>/*.gemspec", tag: "…"` | | Python | `protocolbuffers/python` + `pyi`, `grpc/python` | `pyproject.toml` per module | `pip install "<name> @ git+https://…/protos.git@<ref>#subdirectory=gen/python/<m>"` | Go note: a **single** Go module rooted at `gen/go` is simplest (Go versions per-module are awkward), and Go's build cache still prevents recompiling unchanged packages — so Go can stay monolithic without violating #6. Because the module lives in a subdirectory of `gitlab-org/protos` rather than at the repo root, two things follow: - `gen/go/go.mod` declares `module gitlab.com/gitlab-org/protos/gen/go`, and consumers import `gitlab.com/gitlab-org/protos/gen/go/<proto-package-path>`. GitLab.com serves the `go-import` meta tags and acts as a module proxy, so no vanity-URL infrastructure is needed. - **Release tags must be prefixed with the module's subdirectory**: a release is tagged `gen/go/vX.Y.Z`, not `vX.Y.Z`. That's Go's rule for modules not at the repo root, and it conveniently keeps the Go module's version line independent of the repo's other tags. Rust can be a Cargo workspace of per-module crates. Ruby/Python benefit most from per-module granularity. --- ## Distribution — git-sourced packages (no third-party registries) `gitlab-org/protos` is **public**, and the chosen model is that **every package is consumed directly from this git repo** — nothing is pushed to crates.io, PyPI, or rubygems.org. All four ecosystems support git (and subdirectory) sources as a first-class dependency type. Per language: - **Go** — already git-native; there was never a publish step, only a tag. CI pushes `gen/go/vX.Y.Z`; consumers `go get` it. - **Rust** — Cargo git dependencies select a crate from the `gen/rust` workspace by name and pin the exact commit in `Cargo.lock`. Fingerprint cache rebuilds only changed crates. - **Python** — pip / uv / Poetry resolve `git+…#subdirectory=gen/python/<module>`, building the pure-Python package in place (instant) and caching by URL+commit. - **Ruby** — Bundler git sources with `glob:` locate per-module gemspecs in subdirectories; `Gemfile.lock` pins the revision. No compile step, so an unchanged revision means no reinstall. ### Trade-offs of the git-only model 1. **Ref pins, not semver ranges.** Consumers pin a tag/branch/commit rather than `^1.2`. Updates are explicit ref bumps; Renovate can track them on the consumer side (fully native for Go modules, more variable for the others). 2. **Transitive publish restriction.** crates.io, PyPI, and rubygems.org all reject packages carrying git/direct-URL dependencies. So a consumer that is *itself* a library published to one of those registries cannot depend on these git-sourced packages. Internal GitLab apps and services are unaffected; this only bites a downstream that is a public-registry library. 3. **Clone weight.** A git dependency fetches the whole repo, not just one small package. Package managers cache and reuse the checkout across deps from the same repo, and blobless/partial clone helps — but if `gen/` (four languages) plus vendored protos grows large, first-fetch cost is the one real scaling cost. Splitting `gen/` per language is the escape hatch. 4. **Per-module independent versioning is awkward — and largely unnecessary.** Consumers naturally pin the whole repo to one ref (a consistent schema snapshot) rather than mixing module A@x with B@y. That *simplifies* this design: the content-hash-per-module versioning machinery can be dropped in favour of plain repo tags. Requirement #6 still holds — an unbumped consumer recompiles nothing; on a bump, Go/Rust content-addressed caches skip unchanged crates/packages and Ruby/Python (no compile) just re-resolve. ### Tag scheme **Decision: a single repo-wide version per release, with all tags protected.** Per-module tagging is deferred (see *Later* below). Each release is one version, `vX.Y.Z`, carried by **two tags on the same commit** — because Go won't budge: a module in a subdirectory must be tagged with that subdirectory as a prefix, so the `gen/go` package can *only* be released as `gen/go/vX.Y.Z`, and that prefixed tag applies *only* to the module under `gen/go`. - `vX.Y.Z` — the canonical release tag. Rust/Ruby/Python git consumers pin it (Cargo/pip/Bundler accept any `tag:`/`@ref`); GitLab Releases attach to it; the publish pipeline keys off it. - `gen/go/vX.Y.Z` — a companion tag on the *same commit*, satisfying Go's resolver. It needs no CI action (the public proxy reads it straight from git), so no publish job matches it and its push creates no pipeline. We could collapse to just `gen/go/vX.Y.Z` and have the other languages pin that string too, but a clean `vX.Y.Z` is clearer for humans, Releases, and non-Go consumers. **Apply both together, atomically.** Both tags are two forms of the same SemVer version and must be created on the *same commit* in one release action. If they ever drift to different commits, Go consumers would resolve a different schema snapshot than everyone else — a mismatch that stays invisible until generated Go disagrees with generated Ruby. Encode this in whatever cuts the release (create both refs together) rather than leaving it to a manual two-step; the release identity needs `*` create permission for both. **Protection: one rule, `*`.** Protecting `*` covers every tag — including the slashed `gen/go/v…`, because GitLab's wildcard compiles to a regex where `*` matches across `/`. Set *Allowed to create* to Maintainers plus the release identity (a Project Access Token if you automate tagging — `CI_JOB_TOKEN` pushes don't trigger the tag pipeline). **Simplifications this buys:** - No per-module protected patterns and no per-module CI routing — publish jobs match a single `^v[0-9]+\.[0-9]+\.[0-9]+$`. - If the publish overlays are later enabled, the registry version is just `${CI_COMMIT_TAG#v}` → `X.Y.Z` — no path-prefix stripping, and every package shares one version. **The one trade-off:** a single version bumps *every* package each release, even unchanged ones. Invisible to git-sourced consumers (they pin the repo tag); only becomes republish-churn if you enable the publish overlays — at which point per-module tags are worth reconsidering. **Later — per-module tags.** If a consumer needs independent cadence (or to reduce overlay republishing), move to slash-prefixed `<module>/vX.Y.Z` tags: consistent with Go's mandatory shape, still covered by the same `*` protection, routed per-module via CI regex (`rules: - if: '$CI_COMMIT_TAG =~ /^gitaly\/v/'`), and prefix-stripped for registry versions. Tooling options if you go there: `release-please` in monorepo manifest mode (`include-component-in-tag`, configurable `tag-separator`, cargo-workspace plugin — GitLab support is less first-class than GitHub, so validate) or a roll-your-own main-branch job that diffs affected modules and creates tags via the API (with a Project Access Token). Note: Go stays repo-wide regardless — the single Go module means one `gen/go` tag versions all generated Go; true per-module Go versioning would require splitting `gen/go` into one module per proto module, which fragments the module graph and isn't worth it. --- ## GitLab Package Registry — where it fits (and where it can't, yet) GitLab's own package registry is the natural *first-party* alternative to crates.io/PyPI/rubygems, and it has two advantages: publishing from CI needs **no long-lived secret** (`CI_JOB_TOKEN` authenticates automatically — the thing that made Ruby painful in the public-registry model vanishes), and for a public project consumers can pull **without authenticating** once the *Allow anyone to pull from package registry* toggle is on. That toggle only covers **project-level** endpoints (group/instance endpoints aren't fully supported), but since `gitlab-org/protos` is a single project, project-level endpoints are exactly what you'd use. The blocker is uneven format coverage: | Language | GitLab registry status | Usable for native consumption? | |---|---|---| | Python (PyPI) | GA, native | **Yes** — `pip`/`uv`, semver ranges, anonymous pull on a public project | | Go | git is the native mechanism | N/A — no registry needed; `go get` from the repo | | Rust (Cargo) | No native Cargo format | Only via a shim (e.g. gitlab-cargo-shim) over generic packages | | Ruby (RubyGems) | Experiment, flag-gated | **No** — gems can be stored/downloaded but **not** `bundle install`-ed | So the registry cleanly serves exactly **one** of the four (Python). Ruby's registry is download-only and flag-gated; Rust has no native format; Go doesn't need it. Adopting the registry universally would therefore re-introduce the per-language inconsistency that git-sourcing removes. ### Recommendation Keep **git-sourcing as the uniform baseline** for all four languages. The GitLab PyPI registry is the one spot the registry would add value (native `pip` + semver, and Python consumers avoid cloning the monorepo), but it's **deferred for now** — the initial design ships pure git-sourced with no publish jobs. If revisited, it's `CI_JOB_TOKEN`-only (no stored credential), "allow anyone to pull" keeps consumer pulls auth-free, and Ruby/Cargo registries stay off the table until GitLab ships production RubyGems-install and a native Cargo format. --- ## Publishing is tag-gated The initial design ships **pure git-sourced: no publish jobs at all** — a release is just the tag(s). The GitLab PyPI overlay is deferred and upstream publishing/BSR are out of scope, so there's nothing to publish today. This guidance applies **if and when** any publish job is later added (the GitLab PyPI overlay, or upstream publishing). Such a job must run **only in a release-tag pipeline** — never on a branch, MR, scheduled, or web pipeline: 1. **Job rule** — a single `rules` entry, `- if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/'`, and nothing else. Elsewhere `CI_COMMIT_TAG` is unset, so the job isn't even added to the pipeline. 2. **Dedicated `publish` stage** containing only tag-gated jobs. 3. **Script guard** — `[ -n "$CI_COMMIT_TAG" ] || exit 1` as the job's first line, covering a manually-triggered or retried job. 4. **Protected tags** — the decided `*` protection already restricts tag creation to the release identity, so it doubles as the publish-authorization gate. (A GitLab PyPI overlay job would authenticate with `CI_JOB_TOKEN`; upstream publishing would use OIDC trusted publishing — see *Alternatives*.) --- ## Decisions - **Codegen plugins — remote.** buf remote plugins, version-pinned; no local install. (Air-gap would flip this, but it isn't a constraint.) - **Package granularity — per-module.** One package per proto module per language, with Go kept as a single module (its build cache makes that fine). - **Manifest generation — generated.** Per-module `Cargo.toml` / `pyproject.toml` / `*.gemspec` (and the single `gen/go/go.mod`) are templated as part of the codegen task, not hand-maintained. - **Versioning / tag scheme — single repo-wide version.** Canonical `vX.Y.Z` + companion `gen/go/vX.Y.Z` on the same commit, all tags protected via one `*` rule. Per-module tags deferred. - **GitLab PyPI registry overlay — skipped for now.** Initial design ships pure git-sourced, no publish jobs. Revisit if Python consumers want native `pip`/semver. - **Upstream publishing — deferred.** When we do publish to public registries, it will be via OIDC trusted publishing (crates.io/PyPI from GitLab.com CI; Ruby would need a stored token; Go is N/A). - **BSR — skipped for now.** One residual touchpoint remains: the public-BSR `deps` for well-known types — see below. --- ## Alternatives considered - **BSR (Buf Schema Registry)** — explicitly deferred for now. Would add hosted breaking-change history and per-module-per-language generated SDKs, but it wouldn't commit source into this repo (the stated requirement) and is a registry dependency we're choosing not to take on yet. (The only current BSR touchpoint is the optional public-BSR `deps` for well-known types — vendorable via vendir if you want zero BSR.) - **Upstream publishing (crates.io / PyPI via OIDC)** — deferred for now. git-sourcing covers all four languages without it; revisit if an external consumer needs registry-native semver resolution.