Skip to content

Contributing

enumeratio edited this page Sep 29, 2026 · 39 revisions

Contributing

How to work on enumeratio: the toolchain, the names, where things go, and what a change has to pass before it lands. For parallel work across several sessions, see Lanes; for what to work on, see Roadmap.

Getting started

The repo is a pnpm monorepo on Vite+, whose CLI is vp. vp <name> runs a built-in command; vp run <name> runs a package.json script or a vite.config.ts task.

vp install
pnpm -r --filter "./packages/**" --filter "./upstream/**" run build
vp check
vp test
  • Build the library packages before vp check or the tests: type-aware lint and the tests resolve sibling packages through their dist/. If a sibling's dist is missing on the first pass, run the build again. Keep both filters; a bare pnpm -r run build also builds the site, which takes more than 2 GB.
  • The site is VitePress in web/: pnpm --filter @enumeratio/web run build, or vitepress dev for the dev server.
  • If setup or package-manager behaviour looks wrong, vp env doctor says why.

Names

  • enumeratio is the mathematics: the symbol definitions (collections, statistics and maps, the special functions, the algebras) and their evaluation, built on @cortex-js/compute-engine and written in its language, Epsil.
  • notatio is the interface: the notebook, the <notatio-*> elements, the plots and glyphs, the CLI and REPL, the format registry, the docs site, and the vdom (the component form of an expression). notatio is not a syntax: the text is Epsil.
  • The line runs by what the word governs. enumeratio owns meaning ("a head", "defined as", "evaluates to"); notatio owns writing and showing ("written as", "prints as", InputForm, the *Form heads). See Syntax and Formats.
  • In the reference data, an example's retypeable text form is keyed epsil, and notatio keys its component serialisation, the vdom as Vue/React markup (Examples as Data §2).
  • Symbol names are spelled out, not abbreviated. Package names haven't all caught up; don't rename them in passing (see Component Naming for how renames wait).

Where a change goes

  • Design writing goes on this wiki, not in the repo: settled design under Design, open design under Speculative design.

  • Upstream candidates. A head or fix compute-engine would plausibly take (Wolfram or mpmath has it, or it fixes or widens a native head) is written as a patch in upstream/compute-engine/, not in a symbol package, even before anything is proposed. Its code is laid out as in compute-engine; its reference entries stay in packages/reference/entries/ and never go upstream. See Upstreaming §10.

  • Reference entries. Each head's record is a folder, reference/<Head>/, in the package that declares it (packages/reference/entries/ for compute-engine's own heads):

    • index.md: front matter (summary, signatures, bindings, references…), with the details as a markdown list below it.
    • examples.tsv: one hand-written row per example, in page order. Each row has a stable id (lowercase words joined by -), expr and expected as MathJSON, and each system's hand classification. An example whose value is known from outside our evaluation also carries known, its source (DLMF 25.6.1, OEIS A000110…) and optionally a tolerance. Never "fix" a failing known check by rewriting expected.
    • examples.values.<system>.tsv: generated, one per system: our own forms and each oracle's answers.

    Read and write records through @enumeratio/entry/node, never by hand-parsing their files. After editing, run node packages/reference/scripts/format-records.ts. After adding or changing an example (or a printer or transpiler), run UPDATE_FORMS=1 node packages/frontend/scripts/collect-forms.ts; the forms test says when that's needed. Add a head by adding its folder.

Tests

  • Golden data, not snapshots, in packages/. Assert against a committed golden JSON file (expect(actual).toEqual(golden[id])), regenerated behind an UPDATE_* flag, because it's plain data you can review and reuse. A guard test enforces this.
  • Patches in upstream/ test the way their upstream does, snapshots included, so a test can go upstream with its code.
  • Long sweeps run nightly. A test that samples or enumerates takes a small budget by default and its full one under DEEP_TESTS=1. Keep the important cases in the standard run as fixed examples, not left to the sample. Don't just raise a test timeout.

Git

  • Work on a branch or worktree, never directly on main. Land through a pull request: main requires its status checks, so a direct push skips them. Never force-push main.
  • Never commit conflict markers. After resolving any merge, and before committing: git grep -nE '^(<{7}|>{7})' $(git rev-parse --show-toplevel) must be empty. A marked file landing on main breaks the dev server and every checkout.
  • Commits and PRs are authored as the project (enumeratio), not as a person.
  • No attribution markers in commits, PR descriptions or comments: no Co-Authored-By or other trailers, no "generated with" line, no session links, no footers. This holds for any tool or agent that writes on the project's behalf. When merging a squash, give the message explicitly, since the default adds co-author trailers.

CI and deployment

  • The gate (ci.yml, every push and PR): build the library packages, then vp check, the per-package tests and the site build.
  • Production (enumeratio.dev) ships from GitHub Pages on merge to main.
  • Previews. Every build of every commit also goes up as a Cloudflare Pages preview at <sha7>.enumeratio.pages.dev. The PR's sticky preview comment carries the URL; review links go below its first two lines, which each push rewrites. Previews are cleaned up nightly: a closed PR's a day after it closes, untagged ones after 30 days.
  • Advisory sweeps, never required checks:
    • plausible.yml samples the collection kernels on every push that touches them, and deeply each night (Plausible).
    • nightly.yml rescans the oracle lanes against the committed values nightly: Python (mpmath, SymPy), Julia (Nemo, Combinatorics.jl) and Rust. Each lane also runs the oracle Plausible, which resamples the documented examples toward the edges of each domain. Weekly, it rescans Oscar, Mathlib, Sage and Wolfram the same way.
    • A lane fails when an answered row changes verdict, classification or input, not on a float's printed digits.
    • Failures file rolling issues labelled nightly-fixup. A nightly routine reads them and opens fix PRs, but never merges.

Home

Project

Working

Design: every design page, by subject

Clone this wiki locally