---
url: /guide/contributing.md
---
# Contributing

Thank you for helping improve Twilic. The project spans a specification, eighteen language SDKs, web integrations, tools, and this documentation site.

## Repository map

| Repository | Role |
| --- | --- |
| [`twilic/twilic`](https://github.com/twilic/twilic) | Normative v3 specification and versioned spec snapshots |
| [`twilic/twilic-rust`](https://github.com/twilic/twilic-rust) | Reference implementation and conformance fixtures |
| [`twilic/twilic-*`](https://github.com/twilic) | Language SDKs (Go, Python, Java, …) |
| [`twilic/twilic-js`](https://github.com/twilic/twilic-js) | JavaScript / TypeScript SDK (N-API + WASM) |
| [`twilic/cli`](https://github.com/twilic/cli) | `@twilic/cli` command-line tool |
| [`twilic/axios`](https://github.com/twilic/axios), [`express`](https://github.com/twilic/express), [`fastify`](https://github.com/twilic/fastify), [`fetch`](https://github.com/twilic/fetch), [`hono`](https://github.com/twilic/hono) | Web framework integrations |
| [`twilic/benchmark`](https://github.com/twilic/benchmark) | Benchmark harness |
| [`twilic/examples`](https://github.com/twilic/examples) | Runnable use-case examples (HTTP, WebSocket, telemetry, …) |
| [`twilic/playground`](https://github.com/twilic/playground) | Browser size comparison app |
| [`twilic/website`](https://github.com/twilic/website) | This documentation site |
| [`twilic/workspace`](https://github.com/twilic/workspace) | Dev Container and multi-repo setup script |

## Development workspace

The [`twilic/workspace`](https://github.com/twilic/workspace) repository provides a Dev Container and `setup-twilic-workspace.sh` script that clones all organization repositories and generates a VS Code multi-root workspace file.

Quick start:

1. Authenticate GitHub CLI on the host: `gh auth login`
2. Clone `twilic/workspace` and open it in a Dev Container (VS Code or Cursor).
3. Inside the container, run `./scripts/setup-twilic-workspace.sh`.
4. Open the generated `twilic.code-workspace`.

The container includes Node.js 24, pnpm, Python, Rust, Go, Java, and other toolchains used across Twilic repositories.

## Interoperability and conformance

SDKs are tested against shared binary fixtures generated by the Rust reference implementation.

**v3 SDKs** (Rust, Go, JavaScript, Zig) are v3-interoperable when they:

1. Implement Dynamic Profile canonical rules, compact Bound payloads, `BOUND_STREAM`, and `SCHEMA_BATCH`.
2. Produce output that the reference decoder accepts for the v3 profile.
3. Honor per-message intern table boundaries and reject unnegotiated stateful forms.

**v2 SDKs** remain v2-interoperable when they:

1. Decode all official v2 fixtures correctly.
2. Produce output that the reference decoder accepts for the v2 profile.
3. Honor per-message intern table boundaries and `RESET_STATE` in stateful mode.

See [FAQ — Interoperability](/guide/faq#interoperability), [v3 Reference Profile](/spec/v3), and [v2 Legacy Reference Profile](/spec/v2#interoperability).

## Contributing to this website

Website source lives in [`twilic/website`](https://github.com/twilic/website).

```bash
pnpm install
pnpm dev        # http://localhost:5173
pnpm format     # format markdown, TypeScript, and CSS
pnpm lint       # markdownlint
```

Before opening a pull request:

1. Run `pnpm dev` and verify affected pages.
2. Run `pnpm format` and `pnpm lint`.
3. Fill in all sections of the PR template.

General contribution guidelines (commit messages, issue templates) are described in each repository's `CONTRIBUTING.md`. Website content is released under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).

## Where to start

| Goal | Start here |
| --- | --- |
| Fix a spec ambiguity | [`twilic/twilic`](https://github.com/twilic/twilic) |
| Fix an SDK bug | The language repository (`twilic-go`, `twilic-python`, …) |
| Add a cookbook pattern | This site — `docs/guide/cookbook.md` |
| Add CLI or web integration docs | This site — `docs/guide/` |
| Run all repos locally | [`twilic/workspace`](https://github.com/twilic/workspace) |