José Almeida
2549704bc1
* docs: expand public user and contributor guides * docs: address public guide review feedback * docs: align web e2e coverage guidance * test: cover collapsed docs references * fix: validate shortcut docs references * fix: parse balanced docs links * fix: handle indented docs code blocks
3.8 KiB
title, description
| title | description |
|---|---|
| Contributing to Kandev | Set up the repository, choose the right change boundary, run checks, update public docs, and prepare a reviewable pull request. |
Contributing to Kandev
Kandev is a Go backend, Vite/React web application, Node launcher, Tauri desktop shell, and a collection of runtime helpers. Start by understanding the user-visible behavior and the ownership boundary of the subsystem you intend to change.
Set up the repository
The pinned toolchain is defined in mise.toml: Node 24, pnpm 9.15.9, Go 1.26.0, and supporting tools.
git clone https://github.com/kdlbs/kandev.git
cd kandev
make bootstrap
For browser end-to-end work, also run:
make bootstrap-e2e
make bootstrap installs the pinned tools when needed, installs workspace dependencies, and configures repository hooks. Run make doctor when local and CI behavior disagree.
Start the development application
make dev
This starts the Go backend and Vite web development server with automatic port selection. The terminal output shows the actual URLs. Use make dev-backend or make dev-web when isolating one side.
The production-shaped local path is:
make build
make start
Find the right layer
| Change | Start in |
|---|---|
| Task, workflow, repository, integration, persistence, or API behavior | apps/backend/internal/<domain>/ |
| Agent process, ACP, MCP, terminal, Git, or remote runtime behavior | apps/backend/internal/agent/, agentctl/, or the executor package |
| User interface, state, routing, or browser API calls | apps/web/ |
| CLI launch/install behavior | apps/cli/ and apps/backend/internal/launcher/ |
| Desktop shell behavior | apps/desktop/ |
| Public user documentation | docs/public/ |
| CI/release behavior | .github/workflows/ and scripts/ |
Read the nearest tests and existing domain types before adding a new abstraction. Prefer an established handler/service/repository or API/state/component path over a parallel framework.
Develop with focused checks
During iteration, run the narrowest relevant command. Before opening a PR, run:
make fmt
make typecheck
make test
make lint
Any change under apps/web/ must add or update Playwright coverage in apps/web/e2e/ and run make test-e2e. See Testing for targeted commands and fixture rules.
Update public behavior and docs together
If a change affects commands, configuration, settings, workflows, executors, integrations, APIs, screenshots, status language, or user-facing terminology, update docs/public/** in the same PR.
When adding a page:
- create a flat, stable Markdown slug in
docs/public/; - add title and description frontmatter;
- add the slug once to
docs/public/meta.json; - link it from the relevant overview and related pages;
- run
node scripts/validate-public-docs.mjs.
The full publication contract is in the docs contribution guide.
Prepare the pull request
- Keep one logical change per PR.
- Explain user impact and the technical boundary.
- List exact automated and manual verification.
- Include screenshots or a short recording for UI behavior.
- Call out migrations, new credentials, security changes, or compatibility risks.
- Do not mix generated artifacts, local databases, recordings, or unrelated formatting into the diff.
- Understand and be able to explain any agent-generated code you submit.
The root CONTRIBUTING.md contains the community and licensing policy. By contributing, you agree to the repository's AGPL-3.0 license.