> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sdk.anghami.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> Proto package versioning, backwards compatibility, and the deprecation policy.

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

| Language   | Package                      | Pinning             |
| ---------- | ---------------------------- | ------------------- |
| Go         | `github.com/anghami/sdk/api` | Pin a commit / tag  |
| TypeScript | `@anghami/sdk`               | Pin a version range |
| Swift      | `AnghamiSDK` (SPM)           | Pin a version tag   |
| Java       | `com.anghami:anghami-sdk`    | Pin via Gradle      |
| Python     | `anghami-sdk`                | Pin via pip         |

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.