Versioning

The SDK is versioned at the proto package level, not at the SDK or repo level. Every package is sdk.{service}.v1. Breaking changes ship as v2 packages alongside v1 until consumers migrate.

​

What’s stable

• v1 packages are stable. Once a message, field, enum value, or RPC ships in v1, it does not change incompatibly.
• make breaking enforces this in CI. A PR that introduces a breaking change to v1 fails until reverted.
• Generated code is regenerated, not rewritten. A make generate run on the same proto produces byte-stable output (within tooling versions).

​

What “breaking” means here

buf enforces the strict definition. The non-exhaustive list:

• Removing or renaming a field, message, enum, or RPC.
• Changing a field’s type or number.
• Changing an enum value’s number.
• Removing an enum value (renaming is also breaking).
• Adding a required validation to a previously optional field.

Non-breaking, always allowed:

• Adding new optional fields, messages, RPCs, or enum values.
• Adding new validation rules that loosen existing constraints.
• Improving comments and descriptions.

​

Adding new things

When we ship a new service, RPC, or field:

• It appears in the bundled OpenAPI spec automatically.
• Generated TypeScript / Go / Swift / Java / Python clients pick it up on the next regeneration.
• Existing callers are unaffected.

There is no version pinning per RPC — clients always speak the current v1 shape of the service.

​

Deprecation flow

Eventually, an API surface needs to evolve in a way v1 cannot accommodate. The flow:

1. v2 package introduced alongside v1. Both ship in parallel.
2. v1 operations marked deprecated via proto field/RPC comments.
3. OpenAPI surfaces the deprecation. Generated docs and the bundled spec mark v1 operations as deprecated: true.
4. Migration window. Typically 6–12 months, depending on the surface area touched.
5. v1 removed in a separate, well-announced release.

The SDK has not yet had to remove a v1 — when it does, you will see deprecation notices in the changelog and OpenAPI months before removal.

​

Generated client packaging

Pin to a specific tag in production. Within v1, upgrades are safe.

​

CI gates

Every PR runs:

• buf lint — STANDARD + COMMENTS rules.
• buf breaking --against main — no breaking changes to v1.
• make generate — verifies the generated artifacts match the protos.

If any of these fail, the PR cannot merge. This is what keeps v1 stable.