docs: move CONTRIBUTING.md to the root and rewrite it for this edition (P2.4)
Point contributors to AGENTS.md for the rules, list the current setup and check commands (no build:packages step, no Docker), and drop the team-mode test setup and the stale test counts. docs/CONTRIBUTING.md keeps a one-line pointer because the pull request template links it.
This commit is contained in:
131
CONTRIBUTING.md
Normal file
131
CONTRIBUTING.md
Normal file
@@ -0,0 +1,131 @@
|
|||||||
|
# Contributing to Waggle
|
||||||
|
|
||||||
|
Thank you for helping. This page covers the setup, the checks and how to propose a change.
|
||||||
|
|
||||||
|
**Read [AGENTS.md](AGENTS.md) before you change code.** It is the operating contract for this
|
||||||
|
repository, for people and coding agents alike: what is in scope, the rules that must not be
|
||||||
|
broken, and the commands that verify a change. The decisions behind it are in
|
||||||
|
[docs/oss/adr/](docs/oss/adr/README.md). [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) explains
|
||||||
|
how the parts fit together.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Node.js `^20.19.0` or `>=22.12.0`, and npm. Node 22 is recommended; the release builds bundle
|
||||||
|
22.23.2.
|
||||||
|
- Git.
|
||||||
|
- For the desktop app only: a current Rust toolchain, plus the platform's Tauri prerequisites
|
||||||
|
(on Windows, Visual Studio Build Tools with the C++ workload; see
|
||||||
|
[docs/oss/build-windows.md](docs/oss/build-windows.md)).
|
||||||
|
|
||||||
|
Python, Docker and a database server are not needed.
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
Clone the repository, then in its root:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm ci
|
||||||
|
npm run build # type-checks the web UI and builds it into dist/
|
||||||
|
npm run dev:server # the sidecar on http://localhost:3333, serving dist/
|
||||||
|
```
|
||||||
|
|
||||||
|
Open http://localhost:3333 and add a model in Settings → Models.
|
||||||
|
|
||||||
|
- Workspace packages export their TypeScript source under the `source` condition, which tsx,
|
||||||
|
Vitest, Vite and the sidecar build resolve. You do not need `npm run build:packages` before
|
||||||
|
running or testing; it type-checks the packages and builds their `dist/` for publishing.
|
||||||
|
- The sidecar registers the files in `dist/` when it starts. After `npm run build`, restart it,
|
||||||
|
or new assets return 404.
|
||||||
|
- `npm run dev:web` (Vite) cannot authenticate against the sidecar yet. Use the UI the sidecar
|
||||||
|
serves.
|
||||||
|
- Run one sidecar at a time. To keep test data apart from your own, start it with another data
|
||||||
|
directory: `WAGGLE_DATA_DIR=/tmp/waggle-dev npm run dev:server`.
|
||||||
|
|
||||||
|
Other entry points:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run dev -w @waggle/cli # terminal REPL on the same memory and waggle.db
|
||||||
|
(cd app && npm ci && npm run tauri:build:mac:arm64) # desktop app; see AGENTS.md section 4
|
||||||
|
```
|
||||||
|
|
||||||
|
## Checks
|
||||||
|
|
||||||
|
Run the checks that cover your change before you open a pull request. CI runs them too.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build:packages # tsc -b over every in-scope package
|
||||||
|
npm run typecheck:web # the web UI
|
||||||
|
npx tsc --noEmit --project app/tsconfig.json
|
||||||
|
npm run typecheck:tests # test suites; advisory until existing errors are fixed
|
||||||
|
npm run lint # root config; ignores apps/web
|
||||||
|
(cd apps/web && npx eslint .) # web config
|
||||||
|
npm run check:deps # every imported package is declared in its package.json
|
||||||
|
npm run check:licenses # shipped dependencies allow MIT distribution
|
||||||
|
npm test # root Vitest: packages, tests/, scripts/
|
||||||
|
(cd apps/web && npx vitest run) # web UI tests
|
||||||
|
```
|
||||||
|
|
||||||
|
Some checks fail before your change: [docs/oss/baseline.md](docs/oss/baseline.md) records the
|
||||||
|
known failures and counts. A check that passes there must not start failing.
|
||||||
|
|
||||||
|
End-to-end tests use Playwright (`npm run test:e2e`). They reuse a server already listening on
|
||||||
|
:3333 and its data directory. For an isolated run set `WAGGLE_E2E_REUSE_EXISTING_SERVER=0` and a
|
||||||
|
free `WAGGLE_E2E_PORT`. The e2e web server step runs `npm run build:all`, which rewrites `dist/`.
|
||||||
|
|
||||||
|
Tests live in each package's `tests/` directory, in `apps/web/src` next to the code, and in the
|
||||||
|
root `tests/`. New behavior needs a test; a bug fix needs a test that fails without the fix.
|
||||||
|
|
||||||
|
## Rules that reviews check first
|
||||||
|
|
||||||
|
The full list is in [AGENTS.md](AGENTS.md), section 3. In short:
|
||||||
|
|
||||||
|
- No monetization: no tiers, trials, payments, license checks or upsell.
|
||||||
|
- Memory goes through `MemoryStore` from `@waggle/memory-contract`. No SQL against a memory
|
||||||
|
database, and no knowledge graph in this release.
|
||||||
|
- Team mode (`packages/team-server`, `waggle-dance`, `worker`) is frozen, and self-learning is
|
||||||
|
out of scope.
|
||||||
|
- Every new dependency must allow MIT distribution: no GPL or AGPL code in shipped artifacts.
|
||||||
|
Name its license in the commit message.
|
||||||
|
- Analytics stay opt-in. Never commit a PostHog key or any other secret.
|
||||||
|
- Platform-specific code needs Windows, macOS and Linux paths. End users must not need Python,
|
||||||
|
Docker, a compiler or a developer Node.js install.
|
||||||
|
- Security constraints (secrets in the vault, the injection scanner on external input, no
|
||||||
|
`eval`, an explicit Tauri IPC allowlist, parameterized SQL) are in AGENTS.md, section 8.
|
||||||
|
|
||||||
|
## Code style
|
||||||
|
|
||||||
|
- TypeScript in strict mode, ES modules, `.js` extensions in relative imports, and
|
||||||
|
`import type` for types.
|
||||||
|
- File names in `kebab-case.ts`; React components in `PascalCase.tsx`.
|
||||||
|
- Match the style of the file you change. Do not reformat code you do not otherwise touch.
|
||||||
|
- Search before you add a file: [AGENTS.md](AGENTS.md), section 9, lists modules that already
|
||||||
|
exist.
|
||||||
|
- Code, comments, commit messages and documentation are in English. Write plainly.
|
||||||
|
|
||||||
|
## Commits and pull requests
|
||||||
|
|
||||||
|
- One focused change per pull request. Describe what changed, why, and how you tested it.
|
||||||
|
- Commit messages: `type(scope): summary` in the imperative, for example
|
||||||
|
`fix(server): close the memory recall step when nothing is found`. Types: `feat`, `fix`,
|
||||||
|
`refactor`, `test`, `docs`, `build`, `chore`, `perf`.
|
||||||
|
- Keep commits small enough to review. Do not mix a refactor with a behavior change.
|
||||||
|
- Never commit secrets, `.env` files or personal data.
|
||||||
|
|
||||||
|
## Reporting bugs and security issues
|
||||||
|
|
||||||
|
Open an issue for bugs and feature proposals. Report security vulnerabilities privately as
|
||||||
|
described in [SECURITY.md](SECURITY.md), not in a public issue.
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
**Windows: the sidecar fails to start with an esbuild error** such as
|
||||||
|
`Cannot find module @esbuild/win32-x64`. npm skipped esbuild's platform binary. Install the
|
||||||
|
binary that matches the esbuild version named in the error, without changing `package.json`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm i @esbuild/win32-x64@<version> --no-save
|
||||||
|
```
|
||||||
|
|
||||||
|
**Assets return 404 after a build.** Restart the sidecar; see Setup.
|
||||||
|
|
||||||
|
More user-facing problems are in [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md).
|
||||||
@@ -1,172 +1,3 @@
|
|||||||
# Contributing to Waggle
|
# Contributing
|
||||||
|
|
||||||
## Prerequisites
|
Moved to [CONTRIBUTING.md](../CONTRIBUTING.md) in the repository root.
|
||||||
|
|
||||||
- **Node.js 20+** (required)
|
|
||||||
- **Rust toolchain** (only for the desktop app -- `app/` package)
|
|
||||||
- **Docker** (only for team mode tests -- PostgreSQL and Redis)
|
|
||||||
|
|
||||||
## Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone <repository-url> waggle-os # the public repository location is not decided yet
|
|
||||||
cd waggle-os
|
|
||||||
npm install
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running the App
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Local server / sidecar (http://localhost:3333)
|
|
||||||
cd packages/server && npx tsx src/local/start.ts
|
|
||||||
# — or, from the repo root: npm run dev:server
|
|
||||||
|
|
||||||
# Web app (http://localhost:8080)
|
|
||||||
npm run dev # — or: npm run dev:web
|
|
||||||
|
|
||||||
# Desktop app (requires Rust)
|
|
||||||
cd app && npm run tauri dev
|
|
||||||
|
|
||||||
# CLI REPL
|
|
||||||
cd packages/cli && npx tsx src/index.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running Tests
|
|
||||||
|
|
||||||
Tests are the product's safety net. All PRs must pass the full test suite.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Run all tests (3000+ across 190+ files)
|
|
||||||
npx vitest run
|
|
||||||
|
|
||||||
# Watch mode during development
|
|
||||||
npx vitest
|
|
||||||
|
|
||||||
# Run tests for a specific package
|
|
||||||
npx vitest run packages/core
|
|
||||||
|
|
||||||
# Run a specific test file
|
|
||||||
npx vitest run packages/agent/src/__tests__/tools.test.ts
|
|
||||||
|
|
||||||
# Coverage report
|
|
||||||
npx vitest run --coverage
|
|
||||||
```
|
|
||||||
|
|
||||||
### Test Requirements
|
|
||||||
|
|
||||||
- All existing tests must pass before submitting a PR
|
|
||||||
- New features require accompanying tests
|
|
||||||
- Bug fixes require a regression test
|
|
||||||
- Team mode tests require Docker services running (`docker compose up -d`)
|
|
||||||
|
|
||||||
### Test Organization
|
|
||||||
|
|
||||||
Tests live alongside source files in `__tests__/` directories or as `.test.ts` siblings. The monorepo uses a single Vitest config at the root.
|
|
||||||
|
|
||||||
## Pull Request Process
|
|
||||||
|
|
||||||
1. **Fork** the repository and create a feature branch from `main`
|
|
||||||
2. **Read the CLAUDE.md** for execution rules and product truths
|
|
||||||
3. **Make your changes** following the slice-based approach (one focused change per PR)
|
|
||||||
4. **Write tests** for new functionality
|
|
||||||
5. **Run the full test suite**: `npx vitest run`
|
|
||||||
6. **Verify the build**: `npx tsc --noEmit`
|
|
||||||
7. **Submit a pull request** against `main`
|
|
||||||
8. **Describe your changes**: what was added, what was preserved, what was tested
|
|
||||||
|
|
||||||
### PR Title Format
|
|
||||||
|
|
||||||
Use descriptive titles that indicate the type of change:
|
|
||||||
|
|
||||||
- `feat: add Notion connector` -- new feature
|
|
||||||
- `fix: memory search scope filtering` -- bug fix
|
|
||||||
- `refactor: extract FrameStore from MindDB` -- code restructuring
|
|
||||||
- `test: add coverage for approval gates` -- test additions
|
|
||||||
- `docs: update API reference` -- documentation
|
|
||||||
|
|
||||||
## Code Style
|
|
||||||
|
|
||||||
### TypeScript
|
|
||||||
|
|
||||||
- ESM modules (`"type": "module"` in package.json)
|
|
||||||
- Explicit imports (no barrel re-exports)
|
|
||||||
- Strict TypeScript (`strict: true`)
|
|
||||||
- Use `type` imports where possible: `import type { Foo } from './foo.js'`
|
|
||||||
- Include `.js` extensions in imports (ESM requirement)
|
|
||||||
|
|
||||||
### File Organization
|
|
||||||
|
|
||||||
- One concept per file where practical
|
|
||||||
- Co-locate tests: `foo.ts` and `__tests__/foo.test.ts`
|
|
||||||
- Route files export a Fastify plugin async function
|
|
||||||
- Types go in the `@waggle/shared` package if used across packages
|
|
||||||
|
|
||||||
### Naming Conventions
|
|
||||||
|
|
||||||
- Files: `kebab-case.ts`
|
|
||||||
- Types/Interfaces: `PascalCase`
|
|
||||||
- Functions/variables: `camelCase`
|
|
||||||
- Constants: `UPPER_SNAKE_CASE`
|
|
||||||
- Route handlers: descriptive comments with HTTP method and path
|
|
||||||
|
|
||||||
### Error Handling
|
|
||||||
|
|
||||||
- Route handlers catch errors and return appropriate HTTP status codes
|
|
||||||
- Non-critical operations use try/catch with empty catch (logging is acceptable)
|
|
||||||
- Critical operations throw with descriptive error messages
|
|
||||||
- Avoid swallowing errors silently in core logic
|
|
||||||
|
|
||||||
## Package Structure
|
|
||||||
|
|
||||||
### Adding to an Existing Package
|
|
||||||
|
|
||||||
1. Add your source file in the appropriate directory
|
|
||||||
2. Export from the package's `index.ts` if it's a public API
|
|
||||||
3. Add tests in the `__tests__/` directory
|
|
||||||
4. Run `npx vitest run packages/<name>` to verify
|
|
||||||
|
|
||||||
### Key Directories
|
|
||||||
|
|
||||||
```
|
|
||||||
packages/<name>/
|
|
||||||
src/
|
|
||||||
index.ts # Public exports
|
|
||||||
__tests__/ # Test files
|
|
||||||
package.json # Package metadata
|
|
||||||
tsconfig.json # TypeScript config
|
|
||||||
```
|
|
||||||
|
|
||||||
## Product Rules
|
|
||||||
|
|
||||||
Read `CLAUDE.md` in the repo root for the full execution protocol. Key rules:
|
|
||||||
|
|
||||||
- **Waggle is workspace-native** -- do not collapse into a global chat
|
|
||||||
- **Memory is a product primitive** -- do not treat it as decorative
|
|
||||||
- **Tool transparency matters** -- users see what the agent does
|
|
||||||
- **Approval gates are required** for sensitive operations
|
|
||||||
- **No scope reduction without approval** -- do not simplify features "for now"
|
|
||||||
- **Tests are part of the product** -- not an afterthought
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### Windows: sidecar fails to start with an esbuild platform error
|
|
||||||
|
|
||||||
The Fastify sidecar runs through `tsx`, which uses esbuild. On a clean Windows
|
|
||||||
machine the platform-specific esbuild binary is sometimes not resolved, and
|
|
||||||
`npm run dev:server` (or `npx tsx src/local/start.ts`) fails with an error like
|
|
||||||
`Cannot find module @esbuild/win32-x64` or an esbuild version/host mismatch.
|
|
||||||
|
|
||||||
Fix it by installing the matching Windows esbuild binary without adding it to
|
|
||||||
`package.json`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm i @esbuild/win32-x64@0.28.0 --no-save
|
|
||||||
```
|
|
||||||
|
|
||||||
This affects **Windows only** — macOS and Linux resolve their esbuild binaries
|
|
||||||
normally. The version should match the esbuild your install resolved; `0.28.0`
|
|
||||||
is the known-good pin for the sidecar.
|
|
||||||
|
|
||||||
## Questions?
|
|
||||||
|
|
||||||
Open an issue for architecture questions, feature proposals, or bug reports.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user