Внесок у розробку Oleafly

Дякуємо, що хочете зробити Oleafly кращим! Цей посібник проведе вас від свіжого клону до робочої збірки для розробки, а також описує, як ми розглядаємо й приймаємо зміни.

Способи зробити внесок

• Повідомити про помилку: відкрийте звіт про помилку (відкривається в новій вкладці).
• Попросити нову можливість: відкрийте запит на можливість (відкривається в новій вкладці).
• Повідомте про вразливість приватно, керуючись 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.

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

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, а також 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 (відкривається в новій вкладці) збирає інсталятори для 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 або новішої (відкривається в новій вкладці) ліцензії проєкту.