Carlos Florêncio
74 lines
3.4 KiB
Markdown
74 lines
3.4 KiB
Markdown
# Contributing to Kandev
|
|
|
|
Contributions are welcome! This document covers the basics.
|
|
|
|
## Community
|
|
|
|
Join our [Discord](https://discord.gg/gWdCPGcFCD) to ask questions, discuss ideas, or get help with your contribution before opening a PR.
|
|
|
|
## Important
|
|
|
|
You must understand the code you submit. You're welcome to use AI tools to help write code, but every PR will be reviewed by a human maintainer and the feature you're contributing should be manually tested. If you can't explain what your code does and why, it's not ready to submit.
|
|
|
|
## Contribution language
|
|
|
|
Use English for issues, PRs, documentation, specifications, plans, code
|
|
comments, and review discussion. Product localization values can use their
|
|
target language. Keep the surrounding explanation in English.
|
|
|
|
## Before opening a PR
|
|
|
|
Discuss a large architectural change in an issue before implementation or PR
|
|
creation. A large change includes a new subsystem, a public API or protocol
|
|
change, a persistence or data-model change, a new execution boundary, an
|
|
authentication or permission-model change, or a cross-cutting change across
|
|
subsystems.
|
|
|
|
Describe the problem, proposed direction, affected boundaries, alternatives,
|
|
and migration or compatibility risks in the issue. Wait until maintainers have
|
|
discussed the direction before opening the PR. Link the issue from the PR. If
|
|
an agent is preparing the change, it must stop and report missing discussion
|
|
instead of opening the PR.
|
|
|
|
### Documentation coverage
|
|
|
|
When implementing a feature or fix, update the relevant requirements, system
|
|
design, plan, and work-order files. CI runs a linter to check PR documentation
|
|
coverage.
|
|
|
|
## How to Contribute
|
|
|
|
1. **Fork and branch.** Create a feature branch from `main`.
|
|
2. **Keep PRs small and focused.** Keep one logical change per PR. Split
|
|
unrelated cleanup, refactoring, and feature work. Smaller PRs reduce the
|
|
risk surface, make review easier, and reduce maintainer burden.
|
|
3. **Update public docs when behavior changes.** User-facing docs live in `docs/public/**`. If your change affects CLI commands, config keys, install/deploy flows, workflows, executors, APIs, screenshots, or user-facing terminology, update the relevant public docs in the same PR. See the [public docs contribution guide](docs/public/README.md) when editing navigation or adding a page.
|
|
4. **Test your changes.** Run `make fmt` first, then `make typecheck test lint` before submitting. Manually verify that your feature works end-to-end, and add screenshots or recordings to the PR if it has a UI component. **If your change touches any UI files (anything under `apps/web/`), you must add or update Playwright e2e tests in `apps/web/e2e/` to prevent regressions.** Run them with `make test-e2e`. See [docs/test_e2e_web.md](docs/test_e2e_web.md) for patterns and fixtures.
|
|
|
|
## Bug Reports
|
|
|
|
Search [existing issues](https://github.com/kdlbs/kandev/issues) first. If your bug isn't already reported, open one with:
|
|
|
|
- Steps to reproduce
|
|
- Expected vs actual behavior
|
|
- Environment details (OS, browser, agent type)
|
|
|
|
## Feature Ideas
|
|
|
|
Open an issue describing the feature and the problem it solves. Keep it concise.
|
|
|
|
## Code Quality
|
|
|
|
New code must pass the existing linters and tests:
|
|
|
|
```bash
|
|
make fmt # Format Go and web code
|
|
make typecheck # TypeScript type checking
|
|
make test # Backend + web tests
|
|
make lint # Backend + web linters
|
|
```
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the [AGPL-3.0](LICENSE) license.
|