Contributing and Development

Contributing and Development

Language: English · 简体中文

LWC welcomes focused bug fixes, tests, documentation, compatibility updates, and capabilities grounded in a real Agent workflow. Preserve canonical-state safety and machine-readable contracts before optimizing convenience.

Before starting

Search existing issues and current code first. Open an issue before a large behavior change, new external integration, Store migration, or public contract change so the user problem and acceptance boundary are reviewable.

Small, clearly scoped fixes can go directly to a pull request when the reproduction and expected result are unambiguous.

Do not base a contribution on a maintainer's private HOME, AMC installation, plugin cache, absolute binary path, or undocumented Agent format.

Repository layout

Path	Responsibility
src/	Rust CLI, Store, search, graphs, Work, conversion, MCP, Viewer server, and Agent integration
src/agent/targets/	One handwritten AgentTarget adapter per supported host
tests/	CLI, integration, packaging, release, safety, and platform regression tests
web/	Read-only Viewer source and frontend tests
web/dist/	Embedded Viewer build output tracked with the Rust binary
npm/	npm shim and checksum-verified release-binary installer
.github/workflows/	CI and cross-platform release gates
install.sh and root test helpers	Installation and release verification entry points

Follow the nearest AGENTS.md and repository-native instructions before editing.

Local setup

Requirements are a current Rust toolchain, Git, and Node.js 22 or newer for npm and Viewer work.

git clone https://github.com/JanYork/llm-wiki-cli.git
cd llm-wiki-cli
cargo build --locked
./target/debug/lwc --version

For Viewer work:

cd web
npm ci
npm test
npm run typecheck
npm run build

Optional MarkItDown, AnyDoc, graph-engine, CodeGraph, and Agent-host acceptance should use isolated environments. Do not install optional tools globally merely to make an unrelated unit test pass.

Change principles

• Fix the shared root cause. Trace every caller before patching one symptom.
• Keep SQLite canonical. Markdown, FTS, spans, Work artifacts, and graph sidecars remain derived or deployment-local.
• Preserve JSON contracts. Add typed details rather than requiring message parsing.
• Make partial success explicit. A post-canonical failure needs recovery metadata and an idempotent command.
• Bound dense work. Pagination, limits, cancellation, and query budgets are product behavior.
• Preserve foreign files. Agent install, refresh, migration, and uninstall may touch only proven owned content.
• Use official integration evidence. MCP is standard; host config, Hook, Skill, Instructions, plugin, and permissions formats are not.
• Prefer the smallest complete change. Do not add a framework for one implementation or a configuration knob without a demonstrated need.

Test-driven workflow

For production behavior:

1. write the smallest regression that reproduces the user-visible defect;
2. run it and confirm the expected failure reason;
3. implement the root-cause fix at the shared boundary;
4. rerun the focused test and direct dependents;
5. exercise the real CLI or UI path with isolated data;
6. run the final gates appropriate to the changed surface.

A test that failed because its fixture was wrong is not red evidence. Correct the fixture, then demonstrate the intended product failure before implementing.

Validation by changed surface

Changed surface	Minimum local evidence
Rust formatting or code	cargo fmt --all -- --check plus focused tests
Shared Rust behavior	cargo clippy --locked --all-targets --all-features -- -D warnings and relevant suites
Viewer	frontend unit tests, typecheck, build, and a real browser flow
npm installer	Node package tests plus an isolated install and binary identity check
AgentTarget	global/local install, status, refresh idempotence, uninstall precision, Hook, and MCP acceptance
Graph or Work	real queue/watch terminal state, readback, cancellation or recovery as applicable, and graph verify
Windows path behavior	Windows CI or a real Windows runner; do not claim it from macOS-only tests
Documentation	bilingual semantic review, command check, Markdown lint, and internal-link validation

During development, test the complete modified range and its direct dependents. Do not rerun unchanged expensive suites after every edit. The final CI and release gate still cover the full supported matrix.

Safety tests

State-changing code should cover:

• path containment and symlink ancestors;
• concurrent writers and bounded busy behavior;
• failure before and after canonical commit;
• idempotent retry and cleanup;
• draft/live and project/global isolation;
• Windows file-handle behavior where paths are deleted or replaced;
• foreign configuration preservation;
• secret and oversized-input rejection.

Do not make tests pass with --allow-lint-issues, direct SQLite edits, arbitrary sleeps, or cleanup that deletes the failing evidence before diagnosis.

Documentation contributions

English is canonical, and every core page has a complete Simplified Chinese mirror. Update both in one commit. Chinese should be idiomatic technical prose, not English syntax with Chinese words substituted.

Preserve commands, JSON fields, limits, warnings, and acceptance criteria across languages. Add a sidebar entry only after both pages and every internal link pass. Follow the Wiki style guide.

External contributors cannot open a pull request directly against GitHub's separate Wiki Git repository. Open an issue with the proposed Markdown and evidence unless a maintainer gives direct Wiki write access.

Pull request standard

A pull request should include:

• the user-visible problem and why it matters;
• the chosen scope and deliberate non-goals;
• reproduction or acceptance criteria;
• focused test evidence and real-use evidence;
• compatibility, migration, security, and performance impact;
• documentation changes for public behavior;
• any remaining platform limitation stated without overclaiming.

Keep commits reviewable. Do not combine unrelated formatting, generated-file churn, dependency upgrades, and behavior changes.

Review checklist

• The change matches a demonstrated requirement.
• Canonical and derived boundaries remain explicit.
• Error and partial-success contracts are machine-readable.
• The changed surface and direct dependents have real evidence.
• Optional capabilities remain consent-aware.
• Agent integrations use public official conventions only.
• No secret, private path, or user-owned change was committed.
• English and Chinese documentation remain semantically aligned.

The full maintainer gate and publication order are documented in Testing and release process.