Community

Contribute

qLLM is open for focused improvements — connectors, docs, harness, and the product site — as long as they stay inside the product rules. Full text lives in the repo; this page is the short path.

Code of Conduct

Participation requires the Contributor Covenant (v2.1). Be respectful; no harassment. Report violations privately via GitHub Security Advisories or the maintainer contact on GitHub — not in public issues.

Product rules (do not break these)

Surface Agents use Query IR and catalog SQL. No GraphQL agent API (D17).
Contracts JSON schemas in planning/ win. Update specs before or with code — never invent ad-hoc request shapes.
Safety Read-only by default; row limits required and capped; secrets only via *Env.
Scope Query runtime, not a warehouse. Fail-fast budgets (typical maxSyncMs 15000 ms).

Plain-language decision list: Decisions. Canonical guide: CONTRIBUTING.md.

Fork → branch → pull request

Fork jpandrade30/qLLM on GitHub.
Clone your fork, add upstream, create topic/short-description.
Keep the change focused. Rebase or merge from upstream/main before opening the PR.
Open a PR against main with why / what / how tested.

git remote add upstream https://github.com/jpandrade30/qLLM.git
git fetch upstream
git checkout -b topic/short-description
go vet ./...
go test ./...

PR checklist

Check	When
`CHANGELOG.md` `[Unreleased]`	User-visible or contract changes
Root `README.md`	Operators/agents would notice (flags, auth, connectors, Pages)
`planning/` + schemas	Any protocol / IR / connector capability change
`docs/en/` (+ other languages)	Meaning changes for implementers
Units on numbers	Always: ms, rows, bytes
Decision labels	Link Decisions — no bare `D##` alone
No secrets	Never commit tokens, passwords, or private keys

Contract changes

Changing Query IR, envelopes, preset/catalog shapes, or connector capabilities is a spec change: problem statement → additive vs breaking → update planning/01-decisions.md if needed → schemas and 03/04 docs → then code and tests. Record any protocolVersion bump.

Where to work

Contribution	Path
Runtime / connectors	`internal/`, tests, goldens
Protocol	`planning/` first
Implementer manuals	`docs/{en,pt,es,zh}/`
This site	`site/` (English only)
Harness	Compose + `fixtures/` + `scripts/dev/` (nerdctl)

Bugs and security

Bugs and ideas: GitHub Issues (include version, OS, redacted YAML, typed error codes). Vulnerabilities: Security Advisories only — not public issues.

Ready to open a PR?

Read the full guide in the repo, then fork and ship a focused change.

CONTRIBUTING.md →