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	Canonical monorepo: specification, conformance, and all language runtimes
twilic/twilic → runtimes/	Language SDKs (Rust, Go, JavaScript, Python, …)
twilic/cli	@twilic/cli command-line tool
twilic/axios, express, fastify, fetch, hono, websocket	Web framework integrations
twilic/benchmark	Benchmark harness
twilic/examples	Runnable use-case examples (HTTP, WebSocket, telemetry, …)
twilic/playground	Browser size comparison app
twilic/website	This documentation site
twilic/workspace	Dev Container and multi-repo setup script

Development workspace

The 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, v3 Reference Profile, and v2 Legacy Reference Profile.

Contributing to this website

Website source lives in twilic/website.

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.

Where to start

Goal	Start here
Fix a spec ambiguity	twilic/twilic
Fix an SDK bug	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