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.

Formas de contribuir

• Informar de un error: abre un informe de error (se abre en una pestaña nueva).
• Pedir una función: abre una solicitud de función (se abre en una pestaña nueva).
• Informar de una vulnerabilidad en privado siguiendo SECURITY.md (se abre en una pestaña nueva).
• 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 (se abre en una pestaña nueva)	22.13+	Necesario para pnpm 11
pnpm (se abre en una pestaña nueva)	11.9+	Activa Corepack o instala la versión declarada en package.json
Rust (se abre en una pestaña nueva)	estable (1.77+)	incluye cargo
Dependencias de la plataforma	-	Consulta los requisitos previos de Tauri v2 (se abre en una pestaña nueva) para tu sistema (en Linux: libwebkit2gtk-4.1-dev, librsvg2-dev, patchelf, …)

Primeros pasos

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

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

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 (se abre en una pestaña nueva) 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.

# 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 (se abre en una pestaña nueva) del proyecto.