10 KiB
Contributing to GenOffice
Thanks for your interest in contributing. This document covers the local setup, the checks a change must pass, and the conventions used in this repository.
How changes land here
This GitHub repository is a mirror: development happens in a private tree,
and main here advances through single squashed snapshot commits
(Sync snapshot (<date>)). That is why every file in a sync shows the same
last-commit message, and why nobody — maintainers included — pushes to
main directly.
External pull requests are welcome and are reviewed here. Once a change is
accepted, a maintainer imports it into the private tree with your authorship
preserved as a Co-authored-by: trailer, and it ships to main in the next
snapshot; your PR is then closed with a note pointing at the snapshot that
carried it. GitHub will show the PR as "closed" rather than "merged" — the
code and the attribution still land. Issues and feature requests are handled
directly on this repository as usual.
Repository layout
apps/*— the seven Electron apps (docs, sheets, slides, pdf, markdown, html, shell). Each app is an npm workspace with its ownsrc/main(Electron main process),src/renderer(React UI), andtests/.packages/*— pure TypeScript engine and shared packages (no Electron dependency, unit-tested): docx/pptx engines, AI agent core, providers, i18n, UI kit.apps/sheets/native/xlsx-engine— Rust xlsx engine (runs as a sidecar process) for xlsx import/export.
Engine packages
All pure TypeScript, no Electron dependency, unit-tested (except the UI kit):
packages/docx-engine— docx parsing → block tree (withdocxIndexanchors and passthrough), OOXML fragment generation, byte-level paragraph patching.packages/pptx-engine/packages/pptx-render— pptx model and rendering.packages/pdf2docx— local PDF → DOCX conversion: PDFium character-level extraction, pure-geometry layout analysis, rebuild throughdocx-engine; the same analysis drives the PDF app's PowerPoint and Excel exports.packages/html2docx— local HTML → DOCX conversion: the page is rendered in the app's own Chromium, reduced in-browser to a document intent tree, and written as native OOXML with thedocxlibrary; only visuals with no Word counterpart are screenshotted. Drives the HTML app's Export as Word.packages/file-parse— text extraction for AI attachments (office formats, text formats).packages/agent-core— the AI agent loop and skill composition shared by every app.packages/ai-provider— provider abstraction and streaming for the model backends.packages/ai-search— Genspark auth + web/image search tools.packages/i18n,packages/ui,packages/project-store,packages/electron-utils— shared i18n core, React UI kit, recent-files store, and Electron main-process helpers.
Architecture notes (docx round trip)
open docx ─► archive original by hash (never touched)
─► docx-engine parses word/document.xml top-level elements (w:p / w:tbl / …)
─► Block tree, each block anchored by docxIndex + original XML slice
─► Tiptap streaming editor (manual + AI editing, dirty tracking)
save ─► dirty blocks → OOXML fragments (referencing existing styles only)
─► splice into original document.xml (untouched blocks keep original bytes)
─► repack zip; all other entries copied byte-for-byte
The same philosophy holds in sheets and slides: the original file is the source of truth, edits are applied as narrow patches, and everything the editor didn't touch survives the round trip untouched.
Getting started
Prerequisites: Node 22+, npm 10+, and a Rust toolchain (cargo on PATH,
needed only for the sheets xlsx sidecar).
npm install
npm run fixtures # generate test .docx fixtures (one-time, and after docx-engine changes)
npm run dev # all editors + shell against Vite dev servers
npm run dev:docs # or run a single app
Checks every change must pass
CI runs these on every PR; please run them locally first:
npm run format:check # Prettier check for uncommitted changed/new files
npm run lint # ESLint across the repo (0 errors required; warnings allowed)
npm run typecheck # tsc --noEmit across every workspace
npm test # engine + app unit tests (also runs the Rust sidecar tests)
npm run licenses # production dependency licenses within the permissive allowlist
Formatting is intentionally incremental: existing files are not reformatted unless they are part of your change. Run these exact commands before committing:
npm run format # format uncommitted changed/new files
npm run format:check # verify uncommitted changed/new files
npm run format:check -- --base origin/main # verify committed files on your branch
CI supplies the PR or push base automatically and checks only files changed from that base. This keeps the formatter gate useful without creating a repository-wide formatting diff.
Building installers
Run these from the repository root — they regenerate the third-party notices and build all seven apps before packaging:
npm run dist:mac # dmg + zip
npm run dist:win # nsis installer
Without Apple or Windows signing credentials in the environment these produce unsigned artifacts: code signing and notarization are skipped with a warning rather than failing. That is the expected result for a contributor build.
On macOS, packaging from a repository that lives on an exFAT/FAT32 volume (an
external USB drive, for example) fails because the OS writes hidden ._
AppleDouble sidecar files next to the build output and electron-builder trips
over them. Point the output directory at an APFS path instead of moving the
repository:
BUILD_DIR=/tmp/genoffice-release npm run dist:mac
dist:win additionally expects the xlsx sidecar at the MinGW cross-compilation
path. Building on Windows leaves it under the MSVC target instead, so stage it
first:
cargo build --release --target x86_64-pc-windows-gnu # from apps/sheets/native/xlsx-engine
or copy an existing target/release/xlsx-sidecar.exe to
target/x86_64-pc-windows-gnu/release/.
Environment variables
None are required — the apps run with all of these unset. They exist for testing and local overrides:
| Variable | Effect |
|---|---|
BUILD_DIR |
Override the electron-builder output directory (default apps/shell/release) |
GENOFFICE_USER_DATA |
Override the Electron userData directory (test isolation) |
GENOFFICE_LANG |
Force the UI language instead of following the OS locale |
GENOFFICE_FAKE_UPDATE |
Exercise the updater UI without a real release feed |
GENOFFICE_CLOUD_SLIDE, GENOFFICE_CLOUD_SLIDE_TIER |
Route slide generation through the cloud endpoint |
GSK_API_KEY, GSK_CLI_PATH |
Genspark credentials / CLI location for the built-in AI provider |
AI_SEARCH_DISABLE_GSK, SERPER_API_KEY, TAVILY_API_KEY |
Disable the gsk search backend / supply a Serper or Tavily key |
XLSX_SIDECAR_PATH, XLSX_OPEN_PATH, XLSX_DEBUG_PORT |
Point at a locally built xlsx sidecar and its debug port |
*_DEV_PORT, *_RENDERER_URL |
Per-app Vite dev server ports and renderer URLs (set by npm run dev) |
AI features degrade rather than break without credentials: requests surface an inline sign-in prompt, and web search falls back to a keyless backend.
Coding conventions
- English only in code, comments, commit messages, and docs. User-facing
strings go through the i18n resources (
src/renderer/i18n/, plus the inline main-process dictionaries insrc/main/), which are the only places non-English text belongs (plus test fixture text). - TypeScript everywhere; avoid adding new
anysurfaces where a precise type is cheap. - Tests live in
apps/*/testsandpackages/*/tests(vitest). New engine behavior needs a unit test; renderer-only UI tweaks generally don't. - Playwright/Electron acceptance drivers and Office-app comparison scripts (anything that drives the built app or Word/Excel/PowerPoint on your machine) are local, on-demand tools: keep them out of the tree (they are gitignored) and never wire them into CI.
- Keep files from growing without bound: if you are adding a substantial new concern to an already-large file, prefer a new module.
Commit and PR guidelines
- Small, focused commits with imperative English subject lines
(e.g.
fix docx table border round-trip,add slides chart legend parsing). - A PR should explain why the change is needed, and mention which of the checks above you ran.
- File format fidelity is the core product promise: for changes touching open/save paths (docx/xlsx/pptx), include a round-trip test proving untouched content survives byte-for-byte.
Reporting bugs and requesting features
Use the issue templates. For suspected security issues, do not open a public issue — follow SECURITY.md.
Code of conduct
All community spaces follow the Contributor Covenant; participation implies acceptance.
License and CLA
There is no CLA (contributor license agreement), and we do not plan to add one. By contributing, you agree that your contributions are licensed under the Apache License 2.0 that covers this project — inbound = outbound, per Apache-2.0 §5. Because community contributions keep their Apache-2.0 terms, the open-source core cannot be retroactively relicensed.
The ee/ directory is reserved for future enterprise modules under a
separate license and does not accept external contributions —
pull requests from outside the maintainer team must not modify files under
ee/ (enforced via CODEOWNERS).