Đóng góp cho Oleafly

Cảm ơn bạn vì muốn làm Oleafly tốt hơn! Hướng dẫn này đưa bạn từ một bản clone mới về máy đến một bản build dev chạy được, đồng thời trình bày cách chúng tôi xem xét và hợp nhất các thay đổi.

Các cách đóng góp

Báo cáo lỗi: mở một báo cáo lỗi (mở trong thẻ mới).
Đề xuất tính năng: mở một yêu cầu tính năng (mở trong thẻ mới).
Báo cáo lỗ hổng bảo mật một cách riêng tư bằng cách làm theo SECURITY.md (mở trong thẻ mới).
Gửi pull request: xem bên dưới.

Với bất cứ thứ gì lớn hơn một bản vá nhỏ, hãy mở issue trước để chúng tôi cùng thống nhất hướng tiếp cận trước khi bạn bỏ thời gian.

Điều kiện trước

Công cụ	Phiên bản	Ghi chú
Node.js (mở trong thẻ mới)	22.13+	Được pnpm 11 yêu cầu
pnpm (mở trong thẻ mới)	11.9+	Bật Corepack hoặc cài phiên bản được khai báo trong `package.json`
Rust (mở trong thẻ mới)	stable (1.77+)	bao gồm `cargo`
Dependency nền tảng	-	Xem điều kiện trước của Tauri v2 (mở trong thẻ mới) cho hệ điều hành của bạn (trên Linux: `libwebkit2gtk-4.1-dev`, `librsvg2-dev`, `patchelf`, …)

Bắt đầu

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

Các tệp nhị phân Tectonic, Biber và Typst bị git-ignored một cách có chủ đích: đừng bao giờ commit chúng. Script tải về đặt chúng vào src-tauri/binaries/, đúng nơi bundle.externalBin chờ chúng.

Dự dựng gói production cục bộ

pnpm tauri build

Các bản cài đặt nằm trong src-tauri/target/release/bundle/.

Bố cục dự án

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

Kiểm thử

pnpm test                    # frontend unit tests (Vitest)
cd src-tauri && cargo test --lib   # Rust backend tests

Logic backend chạm tới hệ thống tệp, git hay đường dẫn của người dùng bắt buộc phải có bài kiểm thử. Các hàm hỗ trợ giới hạn đường dẫn (resolve_within, validate_project_id) và các bộ phân tích nhật ký/URL được phủ trong các module #[cfg(test)], hãy mở rộng chúng khi bạn thay đổi mã đó. Ở frontend, phần che LaTeX quyết định trình kiểm tra chính tả/ngữ pháp nhìn thấy gì là thuần khiết và được kiểm thử đơn vị trong src/components/editor/cm/latex-mask.test.ts, hãy thêm một trường hợp ở đó khi bạn thay đổi định nghĩa thế nào là văn xuôi.

Phong cách mã

TypeScript: frontend phải vượt qua kiểm tra kiểu và dựng được bằng pnpm build, và qua cổng lint Biome: pnpm lint (tự sửa phần an toàn bằng pnpm lint:fix). Cổng này chặn khi có lỗi tính đúng đắn. Phần tồn đọng cũ về khả năng tiếp cận và phong cách được báo cáo thành cảnh báo không chặn (xem biome.json). Hãy tránh thêm cảnh báo mới.
Rust: backend phải sạch cargo fmt và sạch cargo clippy. Cả hai đều chặn trong CI (clippy chạy với -D warnings). Hãy chạy cargo fmt và cargo clippy --all-targets --fix trước khi đẩy mã.
Phù hợp với mã xung quanh về mật độ chú thích, cách đặt tên và thành ngữ.

Pull request

Fork và tạo nhánh từ main (git checkout -b fix/short-description).
Giữ thay đổi tập trung. Đặt các refactor không liên quan vào PR riêng.
Chắc chắn pnpm lint, pnpm build và cargo test --lib chạy qua trên máy bạn.
Điền vào mẫu PR: liên kết issue, mô tả thay đổi, ghi chú cách bạn đã kiểm thử.
CI phải xanh (bản dựng frontend và bài kiểm thử Rust là các kiểm tra bắt buộc).

Chúng tôi hợp nhất kiểu squash, nên tiêu đề PR gọn gàng chính là thông điệp commit. Phong cách conventional-commit được hoan nghênh nhưng không bắt buộc (ví dụ fix: reject absolute paths in resolve).

Phát hành (dành cho người bảo trì)

Bản phát hành được cắt bằng cách đẩy một thẻ phiên bản. Release workflow (mở trong thẻ mới) dựng các bản cài đặt macOS Apple Silicon, Windows x64, Linux x64 và Linux ARM64, rồi đính kèm chúng vào một bản nháp để xem xét. Việc xuất bản yêu cầu một lượt chạy workflow được bảo vệ thứ hai cho cùng thẻ đó.

# 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

Bằng cách đóng góp, bạn đồng ý rằng các đóng góp của mình được cấp phép theo GNU Affero General Public License v3.0 hoặc mới hơn (mở trong thẻ mới) của dự án.