Contributing
Contributing
Lettuce is solo-maintained but welcomes PRs and issues. This page is the operational expectations.
Where things are
| URL | Use |
|---|---|
github.com/DrBaher/lettuce |
source code (private during 0.x, public from 1.0) |
github.com/DrBaher/lettuce/issues |
bugs and feature requests |
| https://github.com/DrBaher/notes | the demo vault for https://drbaher.github.io/notes |
| https://lettuce.drbaher.com | landing page |
| https://lettuce.drbaher.com/docs/ | published version of these docs |
Filing an issue
Useful issue title: Tag autocomplete misses nested children (specific).
Bad title: Bug (no information).
Include:
Lettuce version (Lettuce → About).
macOS version (
sw_vers).Reproduction steps.
Expected vs. actual.
Any relevant server stderr output, or a
.lettuce/agent-edits.jsonexcerpt around the time.
For crashes, include the macOS crash log from ~/Library/Logs/DiagnosticReports/Lettuce-*.crash.
PR flow
Branch from
mainwith a descriptive name:feat/tag-autocomplete-nestedorfix/proposal-stale-merge.Make focused commits — one logical change per commit.
All tests must pass:
swift test.Update relevant docs in
Sources/LettuceKit/Docs/.Open the PR with the same descriptive title.
The PR template prompts for: what changes, why, how to test, any user-visible impact.
Commit style
Conventional Commits-flavoured but loose:
feat(server): add `notes_by_tag` MCP tool
Returns notes carrying a tag (or any nested descendant), paginated.
Mirrors the REST `/api/v1/tags/**` endpoint and the existing `list_tags`
shape. Documented in Agent reference/04 Read tools.
Prefixes used: feat:, fix:, docs:, refactor:, test:, chore:, perf:.
Code style
Match the surrounding code. Don’t rewrite to your preferred style in a feature PR.
Sentence-case comments. Periods at end of sentences.
Use
///for public API docs (Markdown),//for inline explanations.Don’t import
FoundationifSwiftis enough.Prefer
letovervar, value types over reference types unless reference semantics are required.
What’s in scope
PRs we love:
Bug fixes with regression tests.
Performance improvements (especially on the 5000+ note path).
New MCP tools that have obvious utility.
More recipes in
Sources/LettuceKit/Docs/Recipes/.Translation / i18n contributions.
PRs that need a design discussion first:
New file formats or breaking schema changes.
Anything that changes the trust model.
UI redesigns.
What’s out of scope
Plugin system (deliberate: keep the surface small).
Mobile / iPad version (separate codebase eventually).
Cloud sync (Lettuce is local-first by design; bring your own sync).
WYSIWYG mode (Live Preview is the line).
License
Lettuce will be open-source under the MIT License at 1.0. Until then, the code is source-available via private repo invite. Contributors retain copyright; PRs come with an implicit DCO-style sign-off.
Code of conduct
Be kind. Disagreements happen; the goal is the product, not winning.