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	Normative v3 specification and versioned spec snapshots
twilic/twilic-rust	Reference implementation and conformance fixtures
twilic/twilic-*	Language SDKs (Go, Python, Java, …)
twilic/twilic-js	JavaScript / TypeScript SDK (N-API + WASM)
twilic/cli	@twilic/cli command-line tool
twilic/axios, express, fastify, fetch, hono	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, 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. The current published SDK line is v2-interoperable when it:

1. Decodes all official fixtures correctly.
2. Produces output that the reference decoder accepts.
3. Honors 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.

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.

Where to start

Goal	Start here
Fix a spec ambiguity	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