Contribuer à Oleafly

Merci de vouloir rendre Oleafly meilleur ! Ce guide vous fait passer d’un clone tout frais à un build de développement fonctionnel, et couvre la façon dont nous examinons et intégrons les changements.

Comment contribuer

• Signaler un bug : ouvrez un rapport de bug (s’ouvre dans un nouvel onglet).
• Demander une fonctionnalité : ouvrez une demande de fonctionnalité (s’ouvre dans un nouvel onglet).
• Signaler une vulnérabilité en privé en suivant SECURITY.md (s’ouvre dans un nouvel onglet).
• Envoyer une pull request : voir ci-dessous.

Pour tout ce qui dépasse un petit correctif, ouvrez d’abord un ticket afin que nous nous mettions d’accord sur l’approche avant que vous n’investissiez du temps.

Prérequis

Outil	Version	Remarques
Node.js (s’ouvre dans un nouvel onglet)	22.13+	Requis par pnpm 11
pnpm (s’ouvre dans un nouvel onglet)	11.9+	Activez Corepack ou installez la version déclarée dans package.json
Rust (s’ouvre dans un nouvel onglet)	stable (1.77+)	inclut cargo
Dépendances de plateforme	-	Voir les prérequis de Tauri v2 (s’ouvre dans un nouvel onglet) pour votre OS (sur Linux : libwebkit2gtk-4.1-dev, librsvg2-dev, patchelf, …)

Pour commencer

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

Les binaires Tectonic, Biber et Typst sont ignorés par git volontairement : ne les commitez jamais. Le script de récupération les dépose dans src-tauri/binaries/, là où bundle.externalBin les attend.

Construire un bundle de production localement

pnpm tauri build

Les installateurs arrivent dans src-tauri/target/release/bundle/.

Organisation du projet

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

Tests

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

Toute logique du backend qui touche le système de fichiers, git ou les chemins utilisateur doit avoir un test. Les utilitaires de confinement des chemins (resolve_within, validate_project_id) et les analyseurs de journaux/URL sont couverts dans des modules #[cfg(test)] : étendez-les quand vous modifiez ce code. Côté frontend, le masquage LaTeX qui détermine ce que voit le correcteur orthographique et grammatical est pur et testé unitairement dans src/components/editor/cm/latex-mask.test.ts : ajoutez-y un cas quand vous changez ce qui compte comme de la prose.

Style de code

• TypeScript : le frontend doit passer la vérification de types et le build (pnpm build), ainsi que le contrôle de lint Biome (pnpm lint ; corrigez automatiquement ce qui est sûr avec pnpm lint:fix). Le contrôle bloque sur les erreurs de correction. Un arriéré existant d’accessibilité ou de style est signalé sous forme d’avertissements non bloquants (voir biome.json). Évitez d’ajouter de nouveaux avertissements.
• Rust : le backend doit être propre pour cargo fmt et cargo clippy. Les deux sont bloquants dans CI (clippy s’exécute avec -D warnings). Exécutez cargo fmt et cargo clippy --all-targets --fix avant de pousser.
• Alignez-vous sur le code environnant : densité des commentaires, nommage et idiomes.

Pull requests

1. Faites un fork et créez une branche depuis main (git checkout -b fix/short-description).
2. Gardez le changement ciblé. Placez les refactorisations sans rapport dans leur propre PR.
3. Assurez-vous que pnpm lint, pnpm build et cargo test --lib passent localement.
4. Remplissez le modèle de PR : liez le ticket, décrivez le changement et indiquez comment vous l’avez testé.
5. CI doit être au vert (le build frontend et les tests Rust sont des contrôles obligatoires).

Nous fusionnons en squash, donc un titre de PR propre sert de message de commit. Le style conventional-commit est apprécié mais non requis (par ex. fix: reject absolute paths in resolve).

Publications (mainteneurs)

Les versions sont créées en poussant un tag de version. Le workflow Release (s’ouvre dans un nouvel onglet) construit les installateurs macOS Apple Silicon, Windows x64, Linux x64 et Linux ARM64. Il les joint à un brouillon pour relecture. La publication exige une seconde exécution protégée du workflow pour le même tag.

# 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

En contribuant, vous acceptez que vos contributions soient sous licence GNU Affero General Public License v3.0 ou version ultérieure (s’ouvre dans un nouvel onglet), celle du projet.