Contributing
How to propose a change to OpenDash, what a pull request needs to pass, and how commits are signed off.
Contributions to the Apache 2.0 core are welcome: bug fixes, connectors, docs, tests and features. The ee/ directory is maintained by the maintainers only.
Before you start
- Open an issue first for anything larger than a small fix, so the approach is agreed before you spend time on it.
- Read
AGENTS.mdin the repository. It lists the rules the code follows (how numbers are checked, tenant isolation, durability, the agent runtime, the design system). Most of them are enforced by lint rules and tests. - Skim the architecture. It is one page.
- Everyone taking part follows the Code of Conduct (
CODE_OF_CONDUCT.md).
Make a change
Set up
Follow Local development: Node 24, pnpm and Docker, then pnpm dx.
Branch from main
Keep the change focused. Follow the nearest existing example of the same kind of thing.
Run what CI runs
pnpm lint && pnpm typecheck && pnpm test && pnpm buildMeasure accuracy changes
Changing prompts, tools, retrieval, the compiler or the answer gate? Run pnpm golden (or pnpm evals) and put the score change in the pull request. These need a model key, so CI doesn't run them.
Open the pull request
Describe what changed and why, and link the issue.
A few more rules:
- New UI components go in
packages/ui, with an entry in the/dev/uigallery. - A new runtime dependency must pass
pnpm check:licenses. See Dependencies. - Examples in code, tests, comments, docs and commit messages come from the demo company (
pnpm demo:seed), never from a real workspace: no customer's company name, table or column names, dashboard titles or values.
Sign your commits
OpenDash uses the Developer Certificate of Origin. Add a Signed-off-by: line to each commit:
git commit -s -m "fix(connectors): retry the ClickHouse connection check once"There is no CLA. By contributing, you agree your work is licensed under the Apache License 2.0.
What CI checks
Every pull request and push to main runs, against a pgvector Postgres:
| Check | What it covers |
|---|---|
pnpm lint | Biome, including the design-system and raw-database rules |
pnpm typecheck | Strict TypeScript across the workspace |
pnpm check:licenses | Every dependency's license against the allowlist |
pnpm test | Unit tests, the tenancy suite (every tenant table has its policies; cross-organization access is denied), theme contrast |
pnpm build | Every package and the web app |
pnpm check:links | Relative links in the Markdown files |
A second workflow builds both images and runs the self-host smoke test: the full stack with Caddy, setup, health over HTTPS, the sign-in page, the worker, and a sign-up through a mail sink.
Reporting bugs and security issues
- Bugs and feature requests: GitHub issues, with your version, how you run OpenDash, and steps to reproduce.
- Vulnerabilities: never in a public issue. See Report a vulnerability.
License and open core
OpenDash is Apache 2.0, except the ee/ directory, which is source-available. What each license allows, what lives where, and the promise about what never moves.
Local development
Run OpenDash from source on your machine, seed sample companies to ask about, and the commands you'll use every day.