# 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` शामिल |
| प्लेटफ़ॉर्म डिपेंडेंसीज़ | - | अपने OS के लिए [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-ignored** हैं - इन्हें कभी कमिट न करें। fetch स्क्रिप्ट उन्हें `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`) और 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](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 or later](https://github.com/Oleafly/Oleafly/blob/main/LICENSE) के अंतर्गत लाइसेंस्ड हैं।