Oleafly への貢献

Oleafly をより良くしたいと考えてくださり、ありがとうございます。このガイドでは、クローンしたばかりの状態から動作する開発ビルドまでの手順と、変更をどのようにレビューして取り込むかを説明します。

貢献の方法

バグを報告する：バグ報告（新しいタブで開きます）の Issue を作成します。
機能を要望する：機能リクエスト（新しいタブで開きます）の Issue を作成します。
脆弱性を非公開で報告する：SECURITY.md （新しいタブで開きます）の手順に従います。
プルリクエストを送る：以下を参照してください。

小さな修正より大きな変更の場合は、時間をかける前に方針を合意できるよう、先に Issue を作成してください。

前提条件

ツール	バージョン	備考
Node.js （新しいタブで開きます）	22.13+	pnpm 11 に必要
pnpm （新しいタブで開きます）	11.9+	Corepack を有効にするか、`package.json` で宣言されているバージョンをインストールしてください
Rust （新しいタブで開きます）	stable (1.77+)	`cargo` を含みます
プラットフォームの依存関係	-	お使いの OS 向けの 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 の lint ゲートも通す必要があります（pnpm lint。安全に直せるものは pnpm lint:fix で自動修正できます）。このゲートは、正しさに関するエラーでブロックされます。既存のアクセシビリティやスタイルの積み残しは、ブロックしない警告として報告されます（biome.json を参照）。新しい警告は増やさないようにしてください。
Rust：バックエンドは cargo fmt と cargo clippy をクリーンに通す必要があります。どちらも CI ではブロックされます（clippy は -D warnings 付きで実行されます）。プッシュする前に cargo fmt と cargo clippy --all-targets --fix を実行してください。
周囲のコードに合わせてください。コメントの量、命名、書き方です。

プルリクエスト

main からフォークしてブランチを作ります（git checkout -b fix/short-description）。
変更は絞ってください。関係のないリファクタリングは別の PR にしてください。
pnpm lint、pnpm build、cargo test --lib がローカルで通ることを確認してください。
PR テンプレートに記入してください。Issue へのリンク、変更内容の説明、テスト方法を書きます。
CI がグリーンである必要があります（フロントエンドのビルドと Rust のテストが必須チェックです）。

スカッシュマージするため、整った PR タイトルがそのままコミットメッセージになります。Conventional Commits の形式だと助かりますが、必須ではありません（例：fix: reject absolute paths in resolve）。

リリース（メンテナー向け）

リリースは、バージョンタグをプッシュして作成します。Release ワークフロー（新しいタブで開きます）が、macOS Apple Silicon、Windows x64、Linux x64、Linux ARM64 のインストーラーをビルドし、レビュー用のドラフトに添付します。公開するには、同じタグに対してガード付きの 2 つ目のワークフローを実行する必要があります。

# 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 以降（新しいタブで開きます）のもとでライセンスされることに同意したものとみなされます。