# Zu Oleafly beitragen

Danke, dass Sie Oleafly besser machen möchten! Dieser Leitfaden führt Sie von einem frischen Clone zu einem laufenden Dev-Build und beschreibt, wie wir Änderungen reviewen und landen.

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](https://github.com/Oleafly/Oleafly/issues/new/choose).
- Ein Feature anfragen: Öffnen Sie eine [Feature-Anfrage](https://github.com/Oleafly/Oleafly/issues/new/choose).
- Eine Schwachstelle privat melden, indem Sie [SECURITY.md](https://github.com/Oleafly/Oleafly/blob/main/SECURITY.md) 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](https://nodejs.org) | 22.13+ | Wird von pnpm 11 benötigt |
| [pnpm](https://pnpm.io) | 11.9+ | Aktivieren Sie Corepack oder installieren Sie die in `package.json` deklarierte Version |
| [Rust](https://rustup.rs) | stable (1.77+) | enthält `cargo` |
| Plattform-Abhängigkeiten | - | Siehe die [Tauri-v2-Voraussetzungen](https://v2.tauri.app/start/prerequisites/) für Ihr Betriebssystem (unter Linux: `libwebkit2gtk-4.1-dev`, `librsvg2-dev`, `patchelf`, …) |

## Erste Schritte

```bash
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

```bash
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

```bash
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](https://github.com/Oleafly/Oleafly/blob/main/.github/workflows/release.yml) 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.

```bash
# 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](https://github.com/Oleafly/Oleafly/blob/main/LICENSE) des Projekts lizenziert sind.