# Участие в разработке Oleafly

Спасибо, что хотите сделать Oleafly лучше! Это руководство проведёт вас от свежего клона репозитория до рабочей dev-сборки и расскажет, как мы рецензируем и принимаем изменения.

Спасибо, что хотите сделать Oleafly лучше! Это руководство проведёт вас от
свежего клона репозитория до рабочей dev-сборки и расскажет, как мы
рецензируем и принимаем изменения.

## Способы внести вклад

- Сообщите об ошибке: откройте [отчёт об ошибке](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`.

### Локальная сборка продакшен-бандла

```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` перед отправкой.
- Следуйте окружающему коду — плотность комментариев, именование и идиомы.

## Pull requests

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)
проекта.