# Contribuir a Oleafly

¡Gracias por querer mejorar Oleafly! Esta guía te lleva de un clon recién hecho a una compilación de desarrollo funcional, y explica cómo revisamos e integramos los cambios.

¡Gracias por querer mejorar Oleafly! Esta guía te lleva de un clon recién hecho a una compilación de desarrollo funcional, y explica cómo revisamos e integramos los cambios.

## Formas de contribuir

- Informar de un error: abre un [informe de error](https://github.com/Oleafly/Oleafly/issues/new/choose).
- Pedir una función: abre una [solicitud de función](https://github.com/Oleafly/Oleafly/issues/new/choose).
- Informar de una vulnerabilidad en privado siguiendo [SECURITY.md](https://github.com/Oleafly/Oleafly/blob/main/SECURITY.md).
- Enviar un pull request: consulta más abajo.

Para cualquier cosa más grande que un arreglo pequeño, abre primero una incidencia para que podamos acordar el enfoque antes de que inviertas tiempo.

## Requisitos previos

| Herramienta | Versión | Notas |
| --- | --- | --- |
| [Node.js](https://nodejs.org) | 22.13+ | Necesario para pnpm 11 |
| [pnpm](https://pnpm.io) | 11.9+ | Activa Corepack o instala la versión declarada en `package.json` |
| [Rust](https://rustup.rs) | estable (1.77+) | incluye `cargo` |
| Dependencias de la plataforma | - | Consulta los [requisitos previos de Tauri v2](https://v2.tauri.app/start/prerequisites/) para tu sistema (en Linux: `libwebkit2gtk-4.1-dev`, `librsvg2-dev`, `patchelf`, …) |

## Primeros pasos

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

> Los binarios de Tectonic, Biber y Typst están **ignorados por git** a propósito: nunca los confirmes. El script de descarga los deja en `src-tauri/binaries/`, que es donde los espera `bundle.externalBin`.

### Crear un paquete de producción en local

```bash
pnpm tauri build
```

Los instaladores quedan en `src-tauri/target/release/bundle/`.

## Estructura del proyecto

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

## Pruebas

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

La lógica del backend que toca el sistema de archivos, git o rutas del usuario **debe** tener una prueba. Los ayudantes que aíslan rutas (`resolve_within`, `validate_project_id`) y los analizadores de registros y URL están cubiertos en módulos `#[cfg(test)]`: amplíalos cuando cambies ese código. En el frontend, el enmascarado de LaTeX que decide qué ve el corrector ortográfico y gramatical es puro y tiene pruebas unitarias en `src/components/editor/cm/latex-mask.test.ts`: añade un caso ahí cuando cambies lo que cuenta como prosa.

## Estilo de código

- **TypeScript**: el frontend debe pasar la comprobación de tipos y compilar con `pnpm build`, y superar la comprobación de lint de Biome con `pnpm lint` (corrige automáticamente lo que sea seguro con `pnpm lint:fix`). La comprobación **bloquea** los errores de corrección. Un atraso existente de accesibilidad y estilo se informa como advertencias que no bloquean (consulta `biome.json`). Procura no añadir advertencias nuevas.
- **Rust**: el backend debe estar limpio para `cargo fmt` y `cargo clippy`. Ambos **bloquean** en CI (`clippy` se ejecuta con `-D warnings`). Ejecuta `cargo fmt` y `cargo clippy --all-targets --fix` antes de subir.
- Sigue el código que lo rodea: densidad de comentarios, nombres y estilo.

## Pull requests

1. Haz un fork y crea una rama desde `main` (`git checkout -b fix/short-description`).
2. Mantén el cambio acotado. Pon las refactorizaciones no relacionadas en su propio PR.
3. Asegúrate de que `pnpm lint`, `pnpm build` y `cargo test --lib` pasan en local.
4. Rellena la plantilla del PR: enlaza la incidencia, describe el cambio e indica cómo lo probaste.
5. La CI debe estar en verde (la compilación del frontend y las pruebas de Rust son comprobaciones obligatorias).

Fusionamos con squash, así que un título de PR claro es el mensaje del commit. Se agradece el estilo de commits convencionales, pero no es obligatorio (por ejemplo, `fix: reject absolute paths in resolve`).

## Versiones (mantenedores)

Las versiones se publican subiendo una etiqueta de versión. El [flujo `Release`](https://github.com/Oleafly/Oleafly/blob/main/.github/workflows/release.yml) compila los instaladores para macOS Apple Silicon, Windows x64, Linux x64 y Linux ARM64. Los adjunta a un borrador para revisarlo. Publicar requiere una segunda ejecución protegida del flujo para la misma etiqueta.

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

Al contribuir, aceptas que tus contribuciones se licencian bajo la [GNU Affero General Public License v3.0 o posterior](https://github.com/Oleafly/Oleafly/blob/main/LICENSE) del proyecto.