Contributing
Thanks for helping. Bug reports, fixes, new blocks, render drivers, voice providers, docs and example projects are all welcome.
By contributing, you agree that your contribution is licensed under the Apache License 2.0, as section 5 of the license says. You keep the copyright to what you write. No separate agreement is needed.
Everyone taking part follows the Code of Conduct.
Before you start
- A bug: open an issue with steps to reproduce. Attach a
project.jsonthat shows it, if you can. - A security problem: don't open an issue. See SECURITY.md.
- Something bigger (a new block type, a change to
project.json, a new driver API): open an issue first, so we can agree on the shape before you write it. Changes toproject.jsonaffect every project people already have.
Setting up
You need Node 22+, pnpm, ffmpeg and ffprobe. For render tests you also need a Chromium (npx playwright install chromium-headless-shell, or set CHROME). edge-tts is only needed to try generated voice by hand.
git clone https://github.com/forinda/formercial.git
cd formercial
pnpm install
pnpm exec kick typegen # generated types; pnpm dev also does this
pnpm test # all tests (render tests skip without Chromium/ffmpeg)
pnpm exec tsc --noEmit
pnpm exec oxlint src
pnpm exec oxfmt src # format; CI checks with --checkTo run the editor, use pnpm dev. It keeps running, so give it its own terminal.
Read the architecture page for how the pieces fit together.
Making a change
- Branch from
main. - Write the test first, watch it fail, then make it pass. Every behavior change comes with a test that fails without it.
- Keep the player deterministic: anything it draws must follow from
talone, with no timers, clocks or CSS transitions. The testsame t gives the same DOMguards this. - Run
pnpm test,tsc --noEmit,oxlint srcandoxfmt --check src. CI runs the same. - Commit with a conventional message:
feat:,fix:,docs:,test:,refactor:,chore:. - Open a pull request and fill in the template. Say what changed for a person using the app, and how you checked it.
If your change affects what a render looks like, attach a frame or a short clip to the pull request.
Code style
- TypeScript, formatted by oxfmt (no semicolons, single quotes, 100 columns).
- Import across folders through the
@/alias (@/core/project). Use./inside a folder. src/corehas no framework code, so the server and the CLI can share it.src/playerruns in the browser only.- Handlers return a value or
reply(...), and failures throwHttpException. A controller only calls a use case; the work goes inuse-cases/. Streams and live events are the exceptions, since they write their own response. - Comments say why, not what. Name things by what people recognise ("recording", "caption"), not how they're built.
- Prefer the platform and what's already here over a new dependency.
- Changes to behavior, commands or configuration update the docs in
site/(pnpm docs:devto preview).
Common contributions
A new block
- Add its fields to
BlockSchemainsrc/core/project.ts. - Add
needs()andmount()toBLOCKSinsrc/player/blocks.ts.mountbuilds the DOM once and returnsdraw(local), which sets everything from the scene's local time. - Add its styles to
src/player/styles.ts, sized invar(--u)so they work in all three formats. - Add its form to
BlockForminsrc/client/editor/scenes.tsx. - Add tests in
src/player/player.test.ts: at least what it shows at a givent. - Add it to the
showcasepreset insrc/presets/index.ts, and toBLOCK_TYPESin its test.
A render driver or voice provider
Write it against RenderDriver (src/core/render/driver.ts) or VoiceProvider (src/core/voice/provider.ts). A driver should:
- report missing tools from
check(); - use the timeline it's given rather than working out its own;
- write its files under the work folder it's handed.
It's usually best to publish a driver as its own package that people add in src/formercial.config.ts. Open an issue if you think it belongs here.
An example project
Add it under projects/<name>/. Use fonts with a license that allows redistribution (Google Fonts are fine), and only media you have the right to share.
Changing the history database
The tables are declared in src/db/schema.ts. After changing them, run pnpm kick db generate <name> and commit what it writes to db/migrations/. Don't run the migrations yourself or ask users to: createHistory applies any pending ones each time it opens the database.
Releasing
Maintainers cut releases with one command. See RELEASING.md.
Reviews
A maintainer reviews every pull request. Expect questions: they're about the change, not about you. Small pull requests get reviewed sooner.