المساهمة في Oleafly

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

طرق المساهمة

• الإبلاغ عن خطأ: افتح تقرير خطأ (يفتح في علامة تبويب جديدة).
• طلب ميزة: افتح طلب ميزة (يفتح في علامة تبويب جديدة).
• الإبلاغ عن ثغرة أمنية سرًّا باتباع SECURITY.md (يفتح في علامة تبويب جديدة).
• إرسال طلب سحب: انظر أدناه.

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

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

الأداة	الإصدار	ملاحظات
Node.js (يفتح في علامة تبويب جديدة)	22.13+	يطلبه pnpm 11
pnpm (يفتح في علامة تبويب جديدة)	11.9+	فعّل Corepack أو ثبّت الإصدار المصرّح به في package.json
Rust (يفتح في علامة تبويب جديدة)	stable (1.77+)	يشمل cargo
تبعيات المنصة	-	انظر المتطلبات المسبقة لـ Tauri v2 (يفتح في علامة تبويب جديدة) لنظام التشغيل لديك (على Linux: libwebkit2gtk-4.1-dev، وlibrsvg2-dev، وpatchelf، …)

البدء

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.

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

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

الاختبارات

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 (يفتح في علامة تبويب جديدة) مثبّتات macOS Apple Silicon وWindows x64 وLinux x64 وLinux ARM64. ويرفقها بمسودة للمراجعة. ويتطلب النشر تشغيلًا ثانيًا محميًا لسير العمل نفسه للوسم نفسه.

# 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 أو أحدث (يفتح في علامة تبويب جديدة).