Zu Oleafly beitragen

Danke, dass Sie Oleafly besser machen möchten! Dieser Leitfaden bringt Sie von einem frischen Klon zu einem funktionierenden Dev-Build und beschreibt, wie wir Änderungen reviewen und landen.

Möglichkeiten beizutragen

• Einen Fehler melden: Öffnen Sie einen Bug-Report (öffnet in einem neuen Tab).
• Ein Feature anfragen: Öffnen Sie eine Feature-Anfrage (öffnet in einem neuen Tab).
• Eine Schwachstelle privat melden, indem Sie SECURITY.md (öffnet in einem neuen Tab) folgen.
• Einen Pull-Request senden: siehe unten.

Für alles, was größer als ein kleiner Fix ist, öffnen Sie zuerst ein Issue, damit wir uns über den Ansatz einig werden können, bevor Sie Zeit investieren.

Voraussetzungen

Werkzeug	Version	Hinweise
Node.js (öffnet in einem neuen Tab)	22.13+	Wird von pnpm 11 benötigt
pnpm (öffnet in einem neuen Tab)	11.9+	Aktivieren Sie Corepack oder installieren Sie die in package.json deklarierte Version
Rust (öffnet in einem neuen Tab)	stable (1.77+)	enthält cargo
Plattform-Abhängigkeiten	-	Siehe die Tauri-v2-Voraussetzungen (öffnet in einem neuen Tab) für Ihr Betriebssystem (unter Linux: libwebkit2gtk-4.1-dev, librsvg2-dev, patchelf, …)

Erste Schritte

git clone https://github.com/Oleafly/Oleafly.git
cd Oleafly
pnpm install

# Find your target with `rustc -vV | grep host`.
bash scripts/fetch-tectonic.sh aarch64-apple-darwin   # or your host triple
bash scripts/fetch-typst.sh aarch64-apple-darwin

# Run the app in dev mode (hot-reloads the frontend, rebuilds Rust on change):
pnpm tauri dev

Die Tectonic-, Biber- und Typst-Binärdateien sind absichtlich git-ignored – committen Sie sie niemals. Das Fetch-Skript legt sie in src-tauri/binaries/ ab, wo bundle.externalBin sie erwartet.

Lokal ein Produktions-Bundle bauen

pnpm tauri build

Installer landen in src-tauri/target/release/bundle/.

Projektstruktur

src/                 React + TypeScript app shell
  components/         UI (editor, pdf, ai, layout, files, …)
  lib/               framework-agnostic helpers (ai-providers, github, …)
  store/             Zustand state slices
packages/            @oleafly/* engine packages, consumed as TypeScript source
src-tauri/src/       Rust backend (Tauri commands)
  commands.rs        Tauri command handlers and compile entry points
  latex_engine.rs    Tectonic and latexmk selection
  mcp/               local MCP server, routing, and native tools
  project.rs         project/file CRUD (path-sandboxed - see `resolve`)
  git.rs             git integration
  github.rs          GitHub OAuth device flow
  paths.rs           path helpers + project-id validation
docs/                user-facing documentation
scripts/             sidecar fetchers, language servers, release checks, icon generation

Tests

pnpm test                    # frontend unit tests (Vitest)
cd src-tauri && cargo test --lib   # Rust backend tests

Backend-Logik, die das Dateisystem, Git oder Benutzerpfade berührt, muss einen Test haben. Die Pfad-Sandboxing-Helfer (resolve_within, validate_project_id) und die Log-/URL-Parser sind in #[cfg(test)]-Modulen abgedeckt – erweitern Sie sie, wenn Sie diesen Code ändern. Im Frontend ist das LaTeX-Masking, das entscheidet, was die Rechtschreib-/Grammatikprüfung sieht, rein und wird in src/components/editor/cm/latex-mask.test.ts unit-getestet – fügen Sie dort einen Fall hinzu, wenn Sie ändern, was als Fließtext gilt.

Codestil

• TypeScript – das Frontend muss typechecken und bauen: pnpm build, und das Biome-Lint-Gate bestehen: pnpm lint (Sicheres mit pnpm lint:fix automatisch beheben). Das Gate blockiert bei Korrektheitsfehlern. Ein bestehender Accessibility-/Style-Rückstand wird als nicht-blockierende Warnungen gemeldet (siehe biome.json). Fügen Sie nach Möglichkeit keine neuen Warnungen hinzu.
• Rust – das Backend muss cargo fmt-sauber und cargo clippy-sauber sein. Beides blockiert in CI (clippy läuft mit -D warnings). Führen Sie cargo fmt und cargo clippy --all-targets --fix vor dem Pushen aus.
• Passen Sie sich an den umgebenden Code an – Kommentardichte, Namensgebung und Idiom.

Pull-Requests

1. Forken und Branch von main anlegen (git checkout -b fix/short-description).
2. Halten Sie die Änderung fokussiert. Legen Sie unverbundene Refactorings in eigene PRs.
3. Stellen Sie sicher, dass pnpm lint, pnpm build und cargo test --lib lokal durchlaufen.
4. Füllen Sie die PR-Vorlage aus – verlinken Sie das Issue, beschreiben Sie die Änderung und notieren Sie, wie Sie sie getestet haben.
5. CI muss grün sein (der Frontend-Build und die Rust-Tests sind erforderliche Checks).

Wir squash-mergen, deshalb ist ein sauberer PR-Titel die Commit-Nachricht. Der Conventional-Commit-Stil ist willkommen, aber nicht erforderlich (z. B. fix: reject absolute paths in resolve).

Releases (Maintainer)

Releases werden durch Pushen eines Version-Tags geschnitten. Der Release-Workflow (öffnet in einem neuen Tab) baut Installer für macOS Apple Silicon, Windows x64, Linux x64 und Linux ARM64. Er hängt sie zur Prüfung an einen Draft an. Das Veröffentlichen erfordert einen zweiten, abgesicherten Workflow-Lauf für dasselbe Tag.

# Bump the version everywhere it's declared (package.json, Cargo.toml,
# Cargo.lock, tauri.conf.json) in one shot, so the tag can't drift:
./scripts/bump-version.sh 0.3.6

git commit -am "chore: release v0.2.0"
git tag v0.2.0 && git push origin v0.2.0

Mit Ihrem Beitrag stimmen Sie zu, dass Ihre Beiträge unter der GNU Affero General Public License v3.0 oder später (öffnet in einem neuen Tab) des Projekts lizenziert sind.