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.

Katkı yolları

• Hata bildirin: bir hata raporu (yeni sekmede açılır) açın.
• Özellik isteyin: bir özellik isteği (yeni sekmede açılır) açın.
• Bir güvenlik açığını özel olarak bildirmek için SECURITY.md (yeni sekmede açılır) 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 (yeni sekmede açılır)	22.13+	pnpm 11 tarafından gereklidir
pnpm (yeni sekmede açılır)	11.9+	Corepack’i etkinleştirin veya package.json içinde bildirilen sürümü kurun
Rust (yeni sekmede açılır)	stable (1.77+)	cargo içerir
Platform bağımlılıkları	-	İşletim sisteminiz için Tauri v2 ön koşullarına (yeni sekmede açılır) bakın (Linux’ta: libwebkit2gtk-4.1-dev, librsvg2-dev, patchelf, …)

Başlarken

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

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

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ışı (yeni sekmede açılır) 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.

# 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 (yeni sekmede açılır) lisansı altında lisanslandığını kabul etmiş olursunuz.