# Oleafly'ya katkıda bulunmak

Oleafly'yı daha iyi hale getirmek istediğiniz için teşekkürler! Bu kılavuz sizi yeni klonlanmış bir depodan çalışan bir geliştirme derlemesine kadar götürür ve değişiklikleri nasıl incelediğimizi ve nasıl birleştirdiğimizi kapsar.

Oleafly'yı daha iyi hale getirmek istediğiniz için teşekkürler! Bu kılavuz sizi yeni klonlanmış bir depodan çalışan bir geliştirme derlemesine kadar götürür ve değişiklikleri nasıl incelediğimizi ve nasıl birleştirdiğimizi kapsar.

## Katkı yolları

- Hata bildirin: bir [hata raporu](https://github.com/Oleafly/Oleafly/issues/new/choose) açın.
- Özellik isteyin: bir [özellik isteği](https://github.com/Oleafly/Oleafly/issues/new/choose) açın.
- Bir güvenlik açığını özel olarak bildirmek için [SECURITY.md](https://github.com/Oleafly/Oleafly/blob/main/SECURITY.md) dosyasındaki adımları izleyin.
- Pull request gönderin: aşağıya bakın.

Küçük bir düzeltmeden daha büyük her şey için önce bir issue açın; böylece zaman harcamadan önce yaklaşım üzerinde anlaşabiliriz.

## Ön koşullar

| Araç | Sürüm | Notlar |
| --- | --- | --- |
| [Node.js](https://nodejs.org) | 22.13+ | pnpm 11 tarafından gereklidir |
| [pnpm](https://pnpm.io) | 11.9+ | Corepack'i etkinleştirin veya `package.json` içinde bildirilen sürümü kurun |
| [Rust](https://rustup.rs) | stable (1.77+) | `cargo` içerir |
| Platform bağımlılıkları | - | İşletim sisteminiz için [Tauri v2 ön koşullarına](https://v2.tauri.app/start/prerequisites/) bakın (Linux'ta: `libwebkit2gtk-4.1-dev`, `librsvg2-dev`, `patchelf`, …) |

## Başlarken

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

> Tectonic, Biber ve Typst ikili dosyaları kasıtlı olarak **git tarafından yok sayılır**, asla commit etmeyin. Getirme betiği onları `src-tauri/binaries/` içine bırakır; `bundle.externalBin` de onları orada bekler.

### Yerelde bir üretim paketi derlemek

```bash
pnpm tauri build
```

Kurulum dosyaları `src-tauri/target/release/bundle/` dizinine düşer.

## Proje düzeni

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

## Testler

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

Dosya sistemine, git'e veya kullanıcı yollarına dokunan backend mantığının bir testi **olmak zorundadır**. Yol korumalı alanı yardımcıları (`resolve_within`, `validate_project_id`) ve günlük/URL ayrıştırıcıları `#[cfg(test)]` modüllerinde kapsanmıştır; bu kodu değiştirdiğinizde bu testleri genişletin. Frontend tarafında, yazım/dil bilgisi denetleyicisinin ne göreceğini belirleyen LaTeX maskelemesi saftır ve `src/components/editor/cm/latex-mask.test.ts` içinde birim testleriyle sınanır; neyin düz metin sayıldığını değiştirdiğinizde oraya bir test durumu ekleyin.

## Kod stili

- **TypeScript** - frontend tip denetiminden geçmeli ve derlemeli: `pnpm build`; ayrıca Biome lint geçidini geçmeli: `pnpm lint` (güvenli olanları `pnpm lint:fix` ile otomatik düzeltin). Geçit, doğruluk hatalarında işlemi **durdurur**. Mevcut erişilebilirlik/stil birikimi engellemeyen uyarılar olarak raporlanır (bkz. `biome.json`). Yeni uyarılar eklemekten kaçının.
- **Rust** - backend `cargo fmt` ve `cargo clippy` açısından temiz olmalıdır. İkisi de CI'da **engellemedir** (`clippy`, `-D warnings` ile çalışır). Push etmeden önce `cargo fmt` ve `cargo clippy --all-targets --fix` çalıştırın.
- Çevredeki kodla uyum sağlayın: yorum yoğunluğu, adlandırma ve deyim açısından.

## Pull request'ler

1. Fork'layın ve `main` üzerinden dal açın (`git checkout -b fix/short-description`).
2. Değişikliği odaklı tutun. İlgisiz yeniden düzenlemeleri kendi PR'larına koyun.
3. `pnpm lint`, `pnpm build` ve `cargo test --lib` komutlarının yerel olarak geçtiğinden emin olun.
4. PR şablonunu doldurun: issue'yu bağlayın, değişikliği açıklayın, nasıl test ettiğinizi not edin.
5. CI yeşil olmalı (frontend derlemesi ve Rust testleri zorunlu denetimlerdir).

Squash-merge ile birleştiriyoruz; bu yüzden temiz bir PR başlığı commit mesajı olur. Conventional-commit tarzı hoş karşılanır ama zorunlu değildir (ör. `fix: reject absolute paths in resolve`).

## Sürümler (bakımcılar)

Sürümler, bir sürüm etiketi push edilerek çıkarılır. [`Release` iş akışı](https://github.com/Oleafly/Oleafly/blob/main/.github/workflows/release.yml) macOS Apple Silicon, Windows x64, Linux x64 ve Linux ARM64 kurulum dosyalarını derler ve inceleme için bir taslağa ekler. Yayınlamak, aynı etiket için ikinci, korumalı bir iş akışı çalıştırması gerektirir.

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

Katkıda bulunarak, katkılarınızın projenin [GNU Affero General Public License v3.0 veya daha sonra](https://github.com/Oleafly/Oleafly/blob/main/LICENSE) lisansı altında lisanslandığını kabul etmiş olursunuz.