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

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

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

• Сообщите об ошибке: откройте отчёт об ошибке (откроется в новой вкладке).
• Предложите функцию: откройте запрос на функцию (откроется в новой вкладке).
• Сообщите об уязвимости конфиденциально, следуя SECURITY.md (откроется в новой вкладке).
• Отправьте pull request: см. ниже.

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

Необходимые компоненты

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

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 (откроется в новой вкладке) собирает установщики для 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 или более поздней (откроется в новой вкладке) проекта.