# Внесок у розробку 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).
- Надішліть pull request: див. нижче.

Для будь-чого більшого за незначне виправлення спершу відкрийте issue, щоб ми могли узгодити підхід, перш ніж ви витратите час.

## Передумови

| Інструмент | Версія | Примітки |
| --- | --- | --- |
| [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`.

### Локальне збирання production-пакета

```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`, а також lint-шлюз Biome: `pnpm lint` (безпечні виправлення — через `pnpm lint:fix`). Шлюз **блокує** за помилок коректності. Наявні давні проблеми доступності й стилю виводяться як неблокуючі попередження (див. `biome.json`). Краще не додавати нових попереджень.
- **Rust** — бекенд повинен бути чистим щодо `cargo fmt` і `cargo clippy`. Обидві перевірки **блокуючі** в CI (`clippy` запускається з `-D warnings`). Виконуйте `cargo fmt` і `cargo clippy --all-targets --fix` перед push.
- Відповідайте навколишньому коду — щільності коментарів, іменуванню та ідіомам.

## Pull request-и

1. Зробіть fork і створіть гілку від `main` (`git checkout -b fix/short-description`).
2. Тримайте зміну сфокусованою. Незв'язані рефакторинги винесіть в окремі PR.
3. Переконайтеся, що `pnpm lint`, `pnpm build` і `cargo test --lib` проходять локально.
4. Заповніть шаблон PR — поставте посилання на issue, опишіть зміну, зазначте, як ви її протестували.
5. CI повинен бути зеленим (збірка фронтенду й тести Rust — обов'язкові перевірки).

Ми робимо squash-merge, тож чиста назва PR стає повідомленням коміта. Стиль Conventional Commits вітається, але не є обов'язковим (напр. `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) ліцензії проєкту.