Contributing to bilig

July 3, 2026 ยท View on GitHub

Thanks for contributing. bilig is an engine-heavy TypeScript monorepo, so the best contributions are small, tested, and explicit about which runtime behavior they change.

Start Here

  • For a first patch, pick a current scoped ticket from docs/starter-issues.md.
  • If this is your first contribution to this repository, start with the first-timers-only queue.
  • If this is your first bilig pull request, use docs/new-contributor-guide.md for the shortest setup, code-map, and first-time command checklist.
  • If you are reporting a formula or workbook bug, include the exact formula, workbook shape, expected result, actual result, and the smallest command or fixture that reproduces it.
  • If you are changing public behavior, add or tighten a regression test before changing implementation.

First Patch Flow

  1. Pick a starter issue and comment with the files you expect to touch, the validation command, and any open assumption.
  2. Run the smallest useful local check before opening a pull request.
  3. Keep the PR tied to one issue, one package or doc path, and one proof command whenever possible.
  4. Open the pull request on GitHub. Maintainers use Forgejo as the primary source-of-truth remote, but public contributor review happens on GitHub.
  5. Open a draft PR early if setup, expected behavior, or scope is unclear.

Local Setup

Use Node 24+, Bun, and pnpm@10.32.1.

pnpm install
pnpm wasm:build
pnpm typecheck
pnpm test

For the app shell:

pnpm dev:web-local

For targeted changes, run the smallest useful gate first:

  • Docs or example-only starter tasks: docs/new-contributor-guide.md#first-time-command-checklist
  • Formula or WorkPaper behavior: pnpm test:correctness:core
  • Formula package changes: pnpm --filter @bilig/formula build
  • Headless package changes: pnpm --filter @bilig/headless build
  • Import/export changes: pnpm test:correctness:xlsx
  • Browser shell changes: pnpm test:browser
  • Docs discovery changes: pnpm docs:discovery:check

Before You Open a PR

Run the narrowest checks that cover your change, then run the full gate when the change is ready to publish.

pnpm lint
pnpm typecheck
pnpm test
pnpm test:browser
pnpm run ci

If a narrower gate is enough for a docs-only or fixture-only patch, say why in the pull request.

If you edit generated protocol, formula inventory, workspace-resolution, or benchmark-baseline sources, regenerate and commit the generated output.

Good First Areas

  • Add formula fixtures and tests for missing Excel-compatible semantics.
  • Turn architecture docs into smaller runnable examples.
  • Improve grid accessibility, keyboard behavior, and focus handling.
  • Add WorkPaper benchmark cases that describe the real spreadsheet pattern they represent.
  • Tighten engine correctness tests around mutation, snapshot, undo/redo, and dependency behavior.

Formula Parity Fixture Walkthrough

Start by reading the existing fixture shape before adding a new case:

  • packages/excel-fixtures/src/ is the canonical formula and workbook-semantics corpus used by @bilig/formula and engine runtime checks.
  • packages/formula/src/compatibility.ts records implementation status and generated inventory metadata for formula families.
  • packages/formula/src/__tests__/fixture-harness.test.ts executes implemented canonical fixtures through the JavaScript evaluator.
  • packages/core/src/__tests__/formula-runtime-correctness.test.ts covers the production runtime path for fixtures that should run through the engine.
  • packages/headless/fixtures/xlsx-corpus/ holds checked-in XLSX cached-result reductions for XLSX fixture compatibility regressions.

A minimal formula-parity contribution should:

  1. Add or tighten one small fixture with an Excel-observed expected result.
  2. Update the compatibility entry only to the status that the implementation actually supports.
  3. Add focused package tests when the fixture exposes behavior not already covered by the harness.
  4. Run the generated checks before opening a PR:
pnpm formula-inventory:check
pnpm formula:dominance:check
pnpm test:correctness:formula

For cached-result workbook reductions, regenerate or verify the headless XLSX fixture corpus instead of hand-editing binary evidence:

pnpm workpaper:xlsx-corpus:fixtures:generate
pnpm workpaper:xlsx-corpus:fixtures:check

Before claiming the work is ready, run pnpm run ci. Do not describe a fixture as full Excel parity; the checked-in fixtures prove only the named formulas, inputs, cached workbook results, and runtime paths they actually cover.

Contribution Rules

  • Keep public APIs boring and stable. Prefer is..., allows..., on..., and on...Change naming.
  • Keep formula semantics in JavaScript first. Promote to WASM only after parity and differential tests are green.
  • Avoid any; lint fails on weak typing and floating promises.
  • Use explicit .js suffixes where nearby ESM imports already do.
  • Do not mix UI rendering, behavior policy, and workbook engine logic in one component when a hook, controller, or package boundary can own one concern.
  • Keep benchmark claims tied to commands, artifacts, counters, or checked-in fixtures.
  • Do not weaken parity, benchmark, generated-file, or clean-diff checks to make a patch pass.

PR Description

Include:

  • what changed
  • why the change belongs in this package
  • commands run
  • benchmark output or screenshots when behavior is visual or performance-related
  • known risk or follow-up work

Small pull requests are easier to review and merge than broad refactors.

Security

Do not post private workbook data, credentials, tokens, or vulnerability details in public issues. Follow SECURITY.md for private security reports.

Source of Truth

Forgejo origin is the primary repo workflow for maintainers. GitHub mirrors the public verification contract and public collaboration surface. External pull requests on GitHub are welcome; maintainers handle any Forgejo-side mirroring needed after review.