Contributing

Punch is built by broadcast engineers, for broadcast engineers. Field experience is as valuable as code.

Ways to contribute

You can…	If you…
Open an issue	Found a bug, hit a wall, or have a clear feature request
Open a discussion	Want to talk about an idea before opening an issue
Send a pull request	Have a fix, a doc improvement, or a small feature
Share field data	Tested against an unusual NAT, encoder, or network and want to share results
Improve the protocol spec	Spotted ambiguity in `docs/protocol.md` or `spec/`

Getting started

git clone https://github.com/FiLORUX/punch.git
cd punch
npm install
npm test          # run the test suite
npm run check     # tsc --noEmit
npm run dev       # start wrangler dev on http://localhost:8787

You need Node 22+ and a Cloudflare account if you want to deploy. The local dev server runs Durable Objects via wrangler’s simulator — no Cloudflare account required for development.

Local secrets

Copy .dev.vars.example to .dev.vars and fill in a 32+ character random string for PUNCH_SECRET. Never commit .dev.vars — it’s gitignored for a reason.

echo "PUNCH_SECRET=$(openssl rand -base64 48)" > .dev.vars

Code style

The project follows a few simple conventions:

TypeScript for everything in src/. Strict mode, no any without a comment explaining why.
British English in code, comments, docs, and commits (colour, initialise, behaviour).
Pedagogical comments — explain the why, not the what. The codebase already has examples of this style; mirror them.
Tests required for new behaviour. The test suite uses @cloudflare/vitest-pool-workers and runs against a real Worker isolate, so it catches bugs that mocks would miss.

We don’t enforce a formatter — the code is consistent enough that manual judgement works. If we ever add Prettier, we’ll add it as a non-blocking CI check.

Commit style

Conventional Commits, present tense, concise:

feat: add latency recommendation engine
fix: correct off-by-one in basePort allocation
refactor: extract session state machine into a module
docs: clarify rendezvous timing in nat-traversal.md
test: add multi-stream registration coverage
chore: bump @cloudflare/workers-types

Prefixes: feat, fix, refactor, docs, test, chore, perf, style, ci, build.

Body is optional. When you add one, focus on why the change is needed — the diff itself shows what changed.

Pull request checklist

Before opening a PR:

Tests pass: npm test
Type check passes: npm run check
New behaviour has tests
No secrets in the diff (CI runs gitleaks, but check yourself first)
Docs updated if you touched the protocol or public API
Commit messages follow the conventional style above

PRs that touch the protocol (src/protocol.ts, docs/protocol.md, spec/) get extra scrutiny — the protocol is a contract with anyone building a Punch client.

What we want most right now

See docs/roadmap.md for the phased plan. The highest-leverage contributions today are:

Field validation — test rendezvous against unusual NAT environments and report results in an issue or PR to docs/field-validation.md.
Encoder integrations — confirm or improve the connection-string generation for hardware encoders we don’t have access to.
Relay-fallback design — Phase 3 architecture discussion is open in GitHub Discussions.
Protocol spec polish — tighten docs/protocol.md MUST/SHOULD wording so a third-party implementor could build a compatible client without reading our source.

What we won’t merge

Code that adds AI attribution to commits, files, or output
Changes that break the free-tier-viable promise without a clear justification (Punch should always work on Cloudflare’s free plan for individual broadcasters)
Features that turn Punch into a media server — relay fallback is in scope, transcoding and CDN behaviour are not
Vendor lock-in — the Punch protocol stays open, the Cloudflare implementation is one of potentially many

Code of conduct

We follow the Contributor Covenant 2.1. Be patient with people learning broadcast jargon and patient with people learning code — both directions matter here.

License

By contributing to Punch you agree that your contributions are licensed under the project’s MIT licence.