Problem
.github/ contains only workflows/. There is no CONTRIBUTING.md, no issue templates, and no pull request template. Someone arriving at the repo has to reverse-engineer from CI what's expected of a patch, and every bug report arrives in whatever shape the reporter chose — which for a realtime media server means the report usually omits the three things needed to act on it (which providers were configured, what the transport was doing, and what the server logged).
AGENTS.md covers conventions for AI coding agents, but nothing addresses human contributors.
Proposed change
CONTRIBUTING.md
Keep it short — a page people actually read. It should cover:
- Build and run locally:
cp config.toml.example config.toml, fill in credentials, go run .. Note which providers work with no API key at all (vibevoice for STT/TTS, ollama for LLM) so a contributor can get a working loop without spending money — this is the single most useful thing the file can say.
- Before you push:
gofmt -l ., go build ./..., go vet ./..., go test -race ./... — the same four things CI runs.
- Testing without provider credentials: point at
internal/tts/http_test.go and internal/stt/deepgram_test.go as the established httptest-based patterns.
- Adding a provider: the switch in
internal/{stt,tts,llm} + a *Config struct + config.toml.example + README table. This is the most common contribution shape and deserves its own short section.
- Commit and PR conventions: whatever the maintainer prefers; the existing history is the reference.
.github/ISSUE_TEMPLATE/bug_report.yml
Required fields should include the things that are always needed and rarely volunteered:
- StreamCore version / commit SHA
- Configured providers (
[stt], [llm], [tts] — or [realtime] if in speech-to-speech mode)
- Client used (which SDK, or browser/WHIP directly)
- Deployment: local, Docker, Cloud Run, EC2 — and whether
server.public_ip/TURN is in play, since NAT traversal is a large share of "no audio" reports
- Server logs around the failure
.github/ISSUE_TEMPLATE/feature_request.yml and config.yml
A slim feature template, plus config.yml linking the Discord for questions so support traffic doesn't land as issues.
.github/pull_request_template.md
Description, linked issue, how it was tested (including "tested against which provider"), and a checkbox for the four CI commands.
Acceptance criteria
Problem
.github/contains onlyworkflows/. There is noCONTRIBUTING.md, no issue templates, and no pull request template. Someone arriving at the repo has to reverse-engineer from CI what's expected of a patch, and every bug report arrives in whatever shape the reporter chose — which for a realtime media server means the report usually omits the three things needed to act on it (which providers were configured, what the transport was doing, and what the server logged).AGENTS.mdcovers conventions for AI coding agents, but nothing addresses human contributors.Proposed change
CONTRIBUTING.mdKeep it short — a page people actually read. It should cover:
cp config.toml.example config.toml, fill in credentials,go run .. Note which providers work with no API key at all (vibevoicefor STT/TTS,ollamafor LLM) so a contributor can get a working loop without spending money — this is the single most useful thing the file can say.gofmt -l .,go build ./...,go vet ./...,go test -race ./...— the same four things CI runs.internal/tts/http_test.goandinternal/stt/deepgram_test.goas the establishedhttptest-based patterns.internal/{stt,tts,llm}+ a*Configstruct +config.toml.example+ README table. This is the most common contribution shape and deserves its own short section..github/ISSUE_TEMPLATE/bug_report.ymlRequired fields should include the things that are always needed and rarely volunteered:
[stt],[llm],[tts]— or[realtime]if in speech-to-speech mode)server.public_ip/TURN is in play, since NAT traversal is a large share of "no audio" reports.github/ISSUE_TEMPLATE/feature_request.ymlandconfig.ymlA slim feature template, plus
config.ymllinking the Discord for questions so support traffic doesn't land as issues..github/pull_request_template.mdDescription, linked issue, how it was tested (including "tested against which provider"), and a checkbox for the four CI commands.
Acceptance criteria
CONTRIBUTING.mdgets someone from clone to a running local server with no paid API keys.