# المساهمة في Oleafly

شكرًا لرغبتك في جعل Oleafly أفضل! يأخذك هذا الدليل من نسخة مستنسخة جديدة إلى بناء تطويري عامل، ويغطي كيفية مراجعتنا للتغييرات وإدخالها.

شكرًا لرغبتك في جعل Oleafly أفضل! يأخذك هذا الدليل من نسخة مستنسخة جديدة إلى بناء تطويري عامل، ويغطي كيفية مراجعتنا للتغييرات وإدخالها.

## طرق المساهمة

- الإبلاغ عن خطأ: افتح [تقرير خطأ](https://github.com/Oleafly/Oleafly/issues/new/choose).
- طلب ميزة: افتح [طلب ميزة](https://github.com/Oleafly/Oleafly/issues/new/choose).
- الإبلاغ عن ثغرة أمنية سرًّا باتباع [SECURITY.md](https://github.com/Oleafly/Oleafly/blob/main/SECURITY.md).
- إرسال طلب سحب: انظر أدناه.

لأي شيء أكبر من إصلاح صغير، افتح مشكلة أولًا حتى نتفق على النهج قبل أن تستثمر وقتك.

## المتطلبات المسبقة

| الأداة | الإصدار | ملاحظات |
| --- | --- | --- |
| [Node.js](https://nodejs.org) | 22.13+ | يطلبه pnpm 11 |
| [pnpm](https://pnpm.io) | 11.9+ | فعّل Corepack أو ثبّت الإصدار المصرّح به في `package.json` |
| [Rust](https://rustup.rs) | stable (1.77+) | يشمل `cargo` |
| تبعيات المنصة | - | انظر [المتطلبات المسبقة لـ Tauri v2](https://v2.tauri.app/start/prerequisites/) لنظام التشغيل لديك (على Linux: `libwebkit2gtk-4.1-dev`، و`librsvg2-dev`، و`patchelf`، …) |

## البدء

```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 وTypst **مستثناة من git** عمدًا - لا تدرجها في أي التزام أبدًا. يضع سكربت الجلب هذه الملفات في `src-tauri/binaries/`، وهو المكان الذي تتوقعها فيه `bundle.externalBin`.

### بناء حزمة إنتاج محليًا

```bash
pnpm tauri build
```

توضع المثبّتات في `src-tauri/target/release/bundle/`.

## تخطيط المشروع

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

## الاختبارات

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

منطق الواجهة الخلفية الذي يتعامل مع نظام الملفات أو git أو مسارات المستخدم **يجب** أن يكون له اختبار. مساعدات حصر المسارات (`resolve_within` و`validate_project_id`) ومحللات السجلات/عناوين URL مغطاة في وحدات `#[cfg(test)]` - وسّعها عندما تغيّر تلك الشيفرة. وفي الواجهة الأمامية، فإن قناع LaTeX الذي يحدد ما يراه المدقق الإملائي/النحوي هو شيفرة نقية مختبرة وحدويًا في `src/components/editor/cm/latex-mask.test.ts` - أضف حالة هناك عندما تغيّر ما يُحتسب نثرًا.

## نمط الشيفرة

- **TypeScript** - يجب أن تجتاز الواجهة الأمامية التحقق من الأنواع والبناء: `pnpm build`، وأن تجتاز بوابة فحص Biome: `pnpm lint` (أصلح تلقائيًا ما هو آمن عبر `pnpm lint:fix`). **تمنع** البوابة عند أخطاء الصحة. ويُبلَّغ عن التراكم القائم من قضايا إمكانية الوصول/النمط كتحذيرات غير مانعة (انظر `biome.json`). يُفضَّل عدم إضافة تحذيرات جديدة.
- **Rust** - يجب أن تكون الواجهة الخلفية نظيفة أمام `cargo fmt` و`cargo clippy`. وكلاهما **مانع** في CI (يعمل `clippy` بخيار `-D warnings`). شغّل `cargo fmt` و`cargo clippy --all-targets --fix` قبل الدفع.
- طابق الشيفرة المحيطة - كثافة التعليقات، والتسمية، والأسلوب المألوف.

## طلبات السحب

1. أنشئ نسخة مشتقة (fork) وتفرّع من `main` (`git checkout -b fix/short-description`).
2. أبقِ التغيير مركّزًا. ضع إعادة الهيكلة غير ذات الصلة في طلب سحب خاص بها.
3. تأكد من نجاح `pnpm lint` و`pnpm build` و`cargo test --lib` محليًا.
4. املأ قالب طلب السحب - اربط المشكلة، وصف التغيير، واذكر كيف اختبرته.
5. يجب أن تكون CI خضراء (بناء الواجهة الأمامية واختبارات Rust فحوصات مطلوبة).

نستخدم الدمج بالحذف (squash-merge)، لذا فإن عنوان طلب سحب نظيف هو رسالة الالتزام. تُقدَّر صيغة الالتزامات التقليدية لكنها ليست مطلوبة (مثل `fix: reject absolute paths in resolve`).

## الإصدارات (للمشرفين)

تُقطع الإصدارات بدفع وسم إصدار. يبني [سير عمل `Release`](https://github.com/Oleafly/Oleafly/blob/main/.github/workflows/release.yml) مثبّتات macOS Apple Silicon وWindows x64 وLinux x64 وLinux ARM64. ويرفقها بمسودة للمراجعة. ويتطلب النشر تشغيلًا ثانيًا محميًا لسير العمل نفسه للوسم نفسه.

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

بمساهمتك، فإنك توافق على أن تكون مساهماتك مرخّصة بموجب [رخصة المشروع GNU Affero General Public License v3.0 أو أحدث](https://github.com/Oleafly/Oleafly/blob/main/LICENSE).