Contribuindo com o Oleafly

Obrigado por querer tornar o Oleafly melhor! Este guia leva você de um clone recente a um build de desenvolvimento funcionando e cobre como revisamos e integramos mudanças.

Formas de contribuir

• Reportar um bug: abra um relatório de bug (abre em uma nova guia).
• Solicitar uma funcionalidade: abra uma solicitação de funcionalidade (abre em uma nova guia).
• Reportar uma vulnerabilidade de forma privada seguindo o SECURITY.md (abre em uma nova guia).
• Enviar um pull request: veja abaixo.

Para qualquer coisa maior que uma pequena correção, abra uma issue primeiro, para que possamos concordar com a abordagem antes de você investir tempo.

Pré-requisitos

Ferramenta	Versão	Observações
Node.js (abre em uma nova guia)	22.13+	Exigido pelo pnpm 11
pnpm (abre em uma nova guia)	11.9+	Ative o Corepack ou instale a versão declarada em package.json
Rust (abre em uma nova guia)	stable (1.77+)	inclui o cargo
Dependências de plataforma	-	Veja os pré-requisitos do Tauri v2 (abre em uma nova guia) para o seu sistema operacional (no Linux: libwebkit2gtk-4.1-dev, librsvg2-dev, patchelf, …)

Primeiros passos

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

Os binários de Tectonic, Biber e Typst são ignorados pelo git de propósito: nunca os commite. O script de busca os coloca em src-tauri/binaries/, que é onde bundle.externalBin espera encontrá-los.

Construindo um bundle de produção localmente

pnpm tauri build

Os instaladores ficam em src-tauri/target/release/bundle/.

Estrutura do projeto

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

Testes

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

A lógica de backend que toca o sistema de arquivos, o git ou caminhos do usuário deve ter um teste. Os auxiliares de sandbox de caminhos (resolve_within, validate_project_id) e os parsers de log/URL são cobertos em módulos #[cfg(test)]: estenda-os quando mudar esse código. No frontend, a máscara de LaTeX que decide o que o verificador ortográfico/gramatical vê é pura e testada em unidade em src/components/editor/cm/latex-mask.test.ts: adicione um caso ali quando mudar o que conta como prosa.

Estilo de código

• TypeScript: o frontend deve passar na verificação de tipos e no build: pnpm build, e passar pelo gate de lint do Biome: pnpm lint (corrija automaticamente o que é seguro com pnpm lint:fix). O gate bloqueia em erros de correção. Um backlog existente de acessibilidade/estilo é reportado como avisos não bloqueantes (veja biome.json). Prefira não adicionar novos avisos.
• Rust: o backend deve estar limpo no cargo fmt e no cargo clippy. Ambos são bloqueantes no CI (o clippy roda com -D warnings). Rode cargo fmt e cargo clippy --all-targets --fix antes de enviar.
• Siga o código ao redor: densidade de comentários, nomes e idiomatismos.

Pull requests

1. Faça um fork e crie um branch a partir de main (git checkout -b fix/short-description).
2. Mantenha a mudança focada. Coloque refatorações não relacionadas em um PR próprio.
3. Certifique-se de que pnpm lint, pnpm build e cargo test --lib passam localmente.
4. Preencha o modelo de PR: vincule a issue, descreva a mudança e indique como você a testou.
5. O CI deve estar verde (o build do frontend e os testes de Rust são verificações obrigatórias).

Fazemos merge com squash, então um título de PR limpo vira a mensagem de commit. O estilo conventional-commit é apreciado, mas não exigido (por exemplo, fix: reject absolute paths in resolve).

Releases (mantenedores)

Releases são criadas enviando uma tag de versão. O workflow Release (abre em uma nova guia) compila instaladores para macOS Apple Silicon, Windows x64, Linux x64 e Linux ARM64, e os anexa a um rascunho para revisão. A publicação exige uma segunda execução protegida do workflow para a mesma 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

Ao contribuir, você concorda que suas contribuições são licenciadas sob a Licença GNU Affero General Public License v3.0 ou posterior (abre em uma nova guia) do projeto.