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 v2 specification and examples
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/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. An implementation 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 and the v2 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