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>
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
- Fork the project on Gitea.
- Branch off
main:git checkout -b your-feature. - Make your changes.
- Run the test suites that cover what you touched.
- Open a merge request against
mainfrom 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 functionalityfix:bug fixdocs:documentation onlyrefactor:non-behavioral code changetest:test-only changechore: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:
- Update grammar.ebnf.
- Update the lexer in nox/parser/src/lexer.js.
- Update the parser rules and AST builder.
- Update the checker for type rules.
- Update the interpreter for runtime behavior.
- 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.