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
104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
---
|
|
title: "Contributing to Kandev"
|
|
description: "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.
|
|
|
|
```bash
|
|
git clone https://github.com/kdlbs/kandev.git
|
|
cd kandev
|
|
make bootstrap
|
|
```
|
|
|
|
For browser end-to-end work, also run:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](testing.md) 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:
|
|
|
|
1. create a flat, stable Markdown slug in `docs/public/`;
|
|
2. add title and description frontmatter;
|
|
3. add the slug once to `docs/public/meta.json`;
|
|
4. link it from the relevant overview and related pages;
|
|
5. run `node scripts/validate-public-docs.mjs`.
|
|
|
|
The full publication contract is in the [docs contribution guide](README.md).
|
|
|
|
## 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.
|
|
|
|
## Next guides
|
|
|
|
- [Architecture](architecture.md)
|
|
- [Backend development](backend-development.md)
|
|
- [Web development](web-development.md)
|
|
- [Testing](testing.md)
|
|
- [Extending Kandev](extending-kandev.md)
|
|
- [Release process](release-process.md)
|