> ## 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.

# Contributing

> How to propose changes to the SDK — proto-first workflow, conventions, and CI gates.

The SDK is open to external contributions in the form of issues, proposals, and pull requests against the proto definitions. **Generated code is not edited by hand** — every change starts in a `.proto` file.

## Workflow

1. **Fork** [github.com/anghami/sdk](https://github.com/anghami/sdk).
2. **Edit `.proto` files** under `sdk/`. Never edit `api/`, `web/`, `swift/Generated/`, `java/generated/`, `python/sdk/`, or `docs/api/`.
3. **`make generate`** to regenerate every language and the OpenAPI bundle.
4. **`make check`** to run lint + breaking + generate. Must pass.
5. **Commit both proto and generated changes** in the same commit.
6. **Open a PR.** CI runs the same `make ci` pipeline.

## Proto conventions

These are enforced by `buf lint` (STANDARD + COMMENTS). See [CLAUDE.md](https://github.com/anghami/sdk/blob/main/CLAUDE.md) in the repo for the full list, but the highlights:

* **Every message, field, enum, enum value, service, and RPC has a leading comment.** The COMMENTS lint rule will fail your PR otherwise.
* **Enum zero values use `_UNSPECIFIED` suffix** (`CONTENT_TYPE_UNSPECIFIED = 0`).
* **Service names end in `Service`** (`MusicCatalogService`, not `MusicCatalog`).
* **IDs are typed messages**, never raw `int64` or `string`.
* **Pagination is always cursor-based** via `sdk.shared.v1.PaginationRequest` / `PaginationResponse`.
* **No cross-service imports.** A service may import from `sdk.shared.v1` but never from another service's package.
* **One file per request/response pair.** `service.proto` only contains the service definition.
* **Validation rules** use `buf.validate` field annotations.

## Breaking changes

`make breaking` runs `buf breaking --against main` and **fails the PR** on any breaking change to a `v1` package. If you genuinely need a breaking change:

1. Introduce a `v2` package alongside `v1`.
2. Mark `v1` operations as deprecated in proto comments.
3. Plan a deprecation window before removing `v1`.

See [Versioning](/versioning).

## Where to file what

* **Bug in generated code** → file a proto-level issue describing the broken behavior; we'll fix the proto and regenerate.
* **Incorrect documentation** → PR against the matching `.mdx` under `docs/`. MDX edits don't require regeneration.
* **New service or operation** → start with an issue describing the use case before opening a proto PR — we want to discuss shape first.
* **Generator improvements** → those go to [sebuf](https://github.com/SebastienMelki/sebuf), not this repo.

## What's out of scope

* Direct edits to generated files. They will be reverted on the next `make generate`.
* Adding live-channel or social-graph operations. See [Overview](/overview) for what's in scope.