Files
caelum/CONTRIBUTING.md
Paul HittandClaude Opus 5.5 1e7e8922ac
ci / lint (pull_request) Successful in 10s
ci / server (mysql) (pull_request) Successful in 11s
ci / nox (pull_request) Successful in 11s
ci / sidecar (pull_request) Failing after 8s
ci / server (sqlite) (pull_request) Successful in 13s
ci / client (pull_request) Successful in 26s
ci / image (pull_request) Skipped
ci / sourcemaps (pull_request) Skipped
ci / deploy (pull_request) Skipped
CI: move to Gitea Actions; deploy over SSH from mac1/mac2
Translate .gitlab-ci.yml into .gitea/workflows/ci.yml with the same
coverage (client, lint, nox, server mysql + sqlite advisory, sidecar,
image build, hadolint, sqlite boot smoke test). Images go to the Gitea
registry as caelum and caelum-reduce. Sourcemaps upload straight to
https://bugs.extant2000.com. Deploy copies the compose and runs
deploy/gitea-deploy.sh on the box over SSH with a throwaway registry
login, waits for healthy, and checks gitSha plus the .map exposure on
the public edge. Repository links now point at git.extant2000.com.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 11:18:58 -04:00

3.8 KiB

Contributing to Caelum

Thanks for your interest. This document describes how to set up the project locally, the conventions we follow, and the merge-request workflow.

Getting set up

See the quick start in README.md. Once npm run dev works, you have everything you need to develop.

Where things live

client/   Vue 3 SPA. Pages in src/views/, components in src/components/.
server/   Express API. Routes in src/routes/, services in src/services/.
nox/      The Nox DSL. Self-contained: parser, runtime, docs, examples.
sql/      Database dumps. Regenerate via `cd server && npm run migrate -- --dump ../sql`.
scripts/  Tooling, including the deploy bundler.

The Nox sub-project is intentionally decoupled from the rest of the codebase. Changes there should not require touching the server or client.

Workflow

  1. Fork the project on Gitea.
  2. Branch off main: git checkout -b your-feature.
  3. Make your changes.
  4. Run the test suites that cover what you touched.
  5. Open a merge request against main from your fork.

Small, focused changes merge faster than large ones. If a feature is big, propose it in an issue first.

Commit style

We follow Conventional Commits loosely. Example types:

  • feat: new functionality
  • fix: bug fix
  • docs: documentation only
  • refactor: non-behavioral code change
  • test: test-only change
  • chore: build, deps, CI

Short subject line under 72 characters. Body paragraphs explain the why, not just the what.

Code style

  • JavaScript / Vue: stick to the existing style. No formatter is enforced; match the surrounding file. Two-space indent, single quotes, no semicolons in script blocks where they're already absent, semicolons elsewhere.
  • Nox: see nox/docs/ for syntax.
  • No emojis or em-dashes in code comments or docs. Plain text reads better in diffs.
  • Verify before asserting. Don't guess flag names, API versions, or commit SHAs. Check the actual code.
  • Short sentences in human-facing text. Long sentences hide assumptions.

Tests

Each sub-project owns its tests.

cd nox/parser  && npm test       # 5 scripts incl. parser, AST, type checker, negative cases
cd nox/runtime && npm test       # interpreter, rollback, policy edges, CLI smoke

The client and server don't have automated tests yet. If you're adding meaningful logic, please include tests; if you're updating UI, manual screenshots in the MR are enough.

Type-check the SPA build by running cd client && npx vite build. The build fails on real errors.

Working with Nox

The Nox parser, type checker, and runtime are pure ES modules with no external dependencies beyond Chevrotain. The interpreter is async and driver-agnostic, so you can plug in a mock driver, the bundled real driver, or your own.

To add a language feature:

  1. Update grammar.ebnf.
  2. Update the lexer in nox/parser/src/lexer.js.
  3. Update the parser rules and AST builder.
  4. Update the checker for type rules.
  5. Update the interpreter for runtime behavior.
  6. Add tests and update nox/docs/.

The IDE highlighter (client/src/views/nox/language.js) and autocomplete table (complete.js) also need updates for any new keyword or method.

Reporting bugs

Open an issue on Gitea with:

  • What you did
  • What you expected to happen
  • What actually happened
  • Steps to reproduce
  • Browser / Node version where relevant

Crash reports go in the body. Don't paste secrets.

Code of conduct

See CODE_OF_CONDUCT.md. Be civil; assume good faith.

License

By contributing, you agree that your contributions will be licensed under the MIT License. See LICENSE.