Contribute without widening the base by accident
Fella’s maintained contribution surface is the application and its model-directed local analytics path. The personal release has no plugin runtime or active extension API.Choose a contribution lane
If a change adds a tool, network path, filesystem capability, or generated
workspace artifact, open an issue first so the product boundary can be reviewed.
Prepare the development environment
- Rust 1.93 or newer.
- Node 22 or newer and pnpm 11.
- Electron runtime libraries on Linux; platform C/C++ build tools and OpenSSL development headers as required by the Rust dependencies.
- A model provider only for live app/evaluation work; deterministic tests do not need one.
Make a focused app change
1
Read the maintained boundary
Start with the product contract, architecture, and design rules.
2
Choose the smallest general implementation
Preserve the model-directed loop and read-only analytics path. Prefer a general capability improvement over a production rule for one fixture or phrase.
3
Add the matching test
Put deterministic checks under the matching
tests/ subdirectory. Keep model-evaluation tasks and graders under bench/; don’t treat one live response as a regression test.4
Run the relevant gates
Run the focused suite,
pnpm check, pnpm build, cargo fmt --manifest-path backend/Cargo.toml --all -- --check, and cargo test --manifest-path backend/Cargo.toml --locked. CI uses the default SQLite features.5
Update the source of truth
Update maintained product or architecture documentation when its claims change. Keep benchmark fixtures, generators, graders, and task-contract versions together.
--features duckdb to default validation.
Tests and model benchmarks must use credentials configured by the person
running them. Run pnpm test:byok-surface when changing a provider fixture or
evaluation entry point. Never commit credentials or include them in output.
Security review prompts
Before opening a PR, ask:- Does this expose a new filesystem or network path?
- Can model-controlled input reach a shell, Python, URL, SQL, or renderer?
- Does it change which prompt or tool result a hosted provider sees?
- Are credentials confined to
auth.json, not settings, browser storage, or transcripts? - Does a read-only claim need qualification for Python or user-authored context?
- Does a verification change detect semantic errors, or only execution/grounding patterns?
Experimental boundary
The/mcp command is inert and creates no connector or network activity. The
root fella.md is the supported user-authored context surface. See the
architecture boundary.
Open a pull request
- Branch from
mainand keep one logical change per PR. - Use the repository’s Conventional Commit style, such as
fix(agent): ...ordocs: .... - Explain the user outcome, design boundary, and verification performed.
- Include tests and maintained documentation updates in the same PR.
- Follow
CONTRIBUTING.mdand the PR template.
Next steps
Choose a test layer
Match deterministic tests and live evaluation to the claim.
Read the product boundary
See which capabilities are in the personal product.