# 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.

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](https://github.com/Oleafly/Oleafly/issues/new/choose).
- Demander une fonctionnalité : ouvrez une [demande de fonctionnalité](https://github.com/Oleafly/Oleafly/issues/new/choose).
- Signaler une vulnérabilité en privé en suivant [SECURITY.md](https://github.com/Oleafly/Oleafly/blob/main/SECURITY.md).
- 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](https://nodejs.org) | 22.13+ | Requis par pnpm 11 |
| [pnpm](https://pnpm.io) | 11.9+ | Activez Corepack ou installez la version déclarée dans `package.json` |
| [Rust](https://rustup.rs) | stable (1.77+) | inclut `cargo` |
| Dépendances de plateforme | - | Voir les [prérequis de Tauri v2](https://v2.tauri.app/start/prerequisites/) pour votre OS (sur Linux : `libwebkit2gtk-4.1-dev`, `librsvg2-dev`, `patchelf`, …) |

## Pour commencer

```bash
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

```bash
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

```bash
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`](https://github.com/Oleafly/Oleafly/blob/main/.github/workflows/release.yml) 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.

```bash
# 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](https://github.com/Oleafly/Oleafly/blob/main/LICENSE), celle du projet.