---
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) | Canonical monorepo: specification, conformance, and all language runtimes |
| [`twilic/twilic` → `runtimes/`](https://github.com/twilic/twilic/tree/main/runtimes) | Language SDKs (Rust, Go, JavaScript, Python, …) |
| [`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), [`websocket`](https://github.com/twilic/websocket) | 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, Bun, 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
bun install
bun run dev        # http://localhost:5173
bun run format     # format markdown, TypeScript, and CSS
bun run lint       # markdownlint
```

Before opening a pull request:

1. Run `bun run dev` and verify affected pages.
2. Run `bun run format` and `bun run 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 | [`twilic/twilic`](https://github.com/twilic/twilic) under `runtimes/<language>/` |
| 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) |