Oleafly में योगदान देना

Oleafly को बेहतर बनाने की इच्छा जताने के लिए धन्यवाद! यह गाइड आपको एक ताज़ा क्लोन से लेकर चलते हुए डेव बिल्ड तक ले जाती है, और बताती है कि हम बदलावों की समीक्षा करके उन्हें कैसे मर्ज करते हैं।

योगदान देने के तरीके

• बग रिपोर्ट करें: एक बग रिपोर्ट (नए टैब में खुलता है) खोलें।
• फीचर का अनुरोध करें: एक फीचर अनुरोध (नए टैब में खुलता है) खोलें।
• किसी भेद्यता की निजी रूप से रिपोर्ट करें: SECURITY.md (नए टैब में खुलता है) का पालन करें।
• पुल रिक्वेस्ट भेजें: नीचे देखें।

छोटे सुधार से बड़ी किसी भी चीज़ के लिए पहले एक इश्यू खोलें, ताकि आप समय लगाने से पहले हम तरीक़े पर सहमत हो सकें।

पूर्व आवश्यकताएँ

टूल	वर्शन	नोट
Node.js (नए टैब में खुलता है)	22.13+	pnpm 11 के लिए ज़रूरी
pnpm (नए टैब में खुलता है)	11.9+	Corepack सक्रिय करें या package.json में घोषित वर्शन इंस्टॉल करें
Rust (नए टैब में खुलता है)	stable (1.77+)	cargo शामिल
प्लेटफ़ॉर्म डिपेंडेंसीज़	-	अपने OS के लिए 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-ignored हैं - इन्हें कभी कमिट न करें। fetch स्क्रिप्ट उन्हें 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) और log/URL पार्सर #[cfg(test)] मॉड्यूल में कवर हैं - जब आप वह कोड बदलें तो उन्हें बढ़ाएँ। फ्रंटएंड पर, LaTeX मास्किंग जो तय करती है कि स्पेल/ग्रामर चेकर क्या देखता है, शुद्ध है और src/components/editor/cm/latex-mask.test.ts में यूनिट-टेस्टेड है - जब आप बदलें कि क्या गद्य माना जाता है, तो वहाँ एक केस जोड़ें।

कोड स्टाइल

• TypeScript - फ्रंटएंड टाइपचेक और बिल्ड होना चाहिए: pnpm build, और Biome लिंट गेट पास करना चाहिए: pnpm lint (जो सुरक्षित है उसे pnpm lint:fix से ठीक किया जा सकता है)। गेट सही-गलत की ग़लतियों पर रोक लगाता है। accessibility/स्टाइल का मौजूदा बैकलॉग नॉन-ब्लॉकिंग चेतावनियों के रूप में आता है (biome.json देखें)। नई चेतावनियाँ न जोड़ना बेहतर है।
• Rust - बैकएंड cargo fmt-स्वच्छ और cargo clippy-स्वच्छ होना चाहिए। दोनों CI में ब्लॉकिंग हैं (clippy -D warnings के साथ चलता है)। पुश करने से पहले cargo fmt और cargo clippy --all-targets --fix चलाएँ।
• आसपास के कोड से मिलान करें - कमेंट घनत्व, नामकरण और तरीक़ा।

पुल रिक्वेस्ट

1. main से फ़ोर्क करें और ब्रांच बनाएँ (git checkout -b fix/short-description)।
2. बदलाव को केंद्रित रखें। असंबंधित रीफ़ैक्टर अपने अलग PR में रखें।
3. सुनिश्चित करें कि pnpm lint, pnpm build और cargo test --lib लोकल रूप से पास हों।
4. PR टेम्पलेट भरें - इश्यू लिंक करें, बदलाव बताएँ, और नोट करें कि आपने उसे कैसे टेस्ट किया।
5. CI हरा होना चाहिए (फ्रंटएंड बिल्ड और Rust टेस्ट ज़रूरी जाँचें हैं)।

हम स्क्वैश-मर्ज करते हैं, इसलिए साफ़ PR शीर्षक ही कमिट मैसेज बनता है। Conventional-commit शैली अच्छी मानी जाती है पर ज़रूरी नहीं (जैसे fix: reject absolute paths in resolve)।

रिलीज़ (मेंटेनर)

रिलीज़ वर्शन टैग पुश करके काटी जाती है। Release workflow (नए टैब में खुलता है) 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 or later (नए टैब में खुलता है) के अंतर्गत लाइसेंस्ड हैं।