Skip to main content

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.
The developer setup guide lists platform requirements and provider setup.

Make a focused app change

1

Read the maintained boundary

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.
DuckDB is optional and is not part of the normal release/CI path. Do not add --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?
State the actual boundary in documentation and tests rather than broadening a guarantee.

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

  1. Branch from main and keep one logical change per PR.
  2. Use the repository’s Conventional Commit style, such as fix(agent): ... or docs: ....
  3. Explain the user outcome, design boundary, and verification performed.
  4. Include tests and maintained documentation updates in the same PR.
  5. Follow CONTRIBUTING.md and 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.