Thanks for helping. localcode aims to stay small, dependable and easy to run, and contributions of every size are welcome: a wrong verdict report is as useful as a new feature.
- Questions and ideas: open a feature request.
- Bugs: open a bug report. If a correct solution was rejected, use wrong verdict instead.
- Security issues: report them privately (see SECURITY.md).
Everyone taking part is expected to follow the Code of Conduct.
You need Docker (with Compose v2), Python 3.14, Node 26 and make.
git clone https://github.com/RyPope/localcode.git && cd localcode
make setup # Python venv in backend/.venv + web dependencies
make up # full stack at http://localhost:4173 (first run imports ~200 MB of data)
make dev-web # optional: hot-reloading UI on http://localhost:5173 against the running APImake help lists every command. Optionally, install the commit hooks with pip install pre-commit && pre-commit install.
| Directory | What lives there |
|---|---|
backend/localcode/importer |
Downloads the open datasets and builds content.db |
backend/localcode/judging |
Output comparison, verdict grading (pure), and the runner client |
backend/localcode/services |
One module per feature; response types in models.py |
backend/localcode/api |
FastAPI app factory and thin routers |
runner/ |
The sandbox: languages.py, sandbox.py, and a harness per language in harness/ |
web/src |
React app: pages/, components/, hooks/, lib/, generated API types in generated/ |
docs/architecture.md explains how the pieces fit together and documents the runner protocol.
- For anything bigger than a small fix, open an issue first so we can agree on the approach.
- Branch from
main, write a failing test, make it pass. - Run
make lintandmake test(CI runs the same checks, plus image builds). - Open a pull request. The template has a short checklist.
- Tests first. Behaviour changes come with a test that fails without the change. Backend tests use small hand-written fixtures in
backend/tests/fixtures. Never commit problem statements, tests or solutions copied from elsewhere (fixtures orcontent/). - Keep layers apart. Routes stay thin and logic lives in
services/. Grading rules live injudging/verdicts.pyand are pure. Anything user-facing that can fail raisesServiceError. - Runner changes need a test in
runner/testsfor every language they affect. - API contract. Responses are
TypedDicts inbackend/localcode/services/models.py. After changing one, runmake api-typesand commitweb/openapi.jsonandweb/src/generated/; CI fails if they're stale. Never edit generated files by hand. - Frontend. Server state goes through TanStack Query, page filters belong in the URL (
useQueryParams), and stateful logic goes in hooks rather than page components. Styles go intheme.css(shared primitives) or a co-located CSS Module; inlinestyleis only for values computed at runtime. - user.db is precious. Schema changes go through a new entry in
USER_MIGRATIONS(backend/localcode/db.py); never edit an existing migration. - Commits follow Conventional Commits (
feat:,fix:,refactor:,docs:,chore:). - UI changes include before/after screenshots in the PR. If README images change, regenerate them with
make screenshots.
New problems, extra solutions and corrected test cases go in content/ as Markdown and JSON files; that page describes the format. Run make validate-content with the stack up before opening the PR. CI runs the same check, which runs every solution against its tests in the sandbox. Contribute only material you wrote yourself.
- Write solutions for problems the upstream data has few of (Kotlin especially), in
content/. - Triage wrong verdicts. Reproduce a reported case and, if the test case itself is invalid, add it to the exclusion list.
- Kotlin reference solutions. The upstream dataset has very few, so the Solutions tab falls back to Java. Contributing Kotlin solutions upstream to doocs/leetcode helps everyone.
- Answer checkers for problems that accept several valid answers and don't have one yet. A checker is a small function in
backend/localcode/judging/checkers/that decides whether an answer is valid for the inputs; see the existing ones and their tests, and runmake check-checkers. - Accessibility and keyboard navigation improvements in the web app.
- Docs: troubleshooting tips for platforms we haven't tested (Windows, Linux distributions, low-memory machines).
- Add the toolchain to
runner/Dockerfile, pinned to an exact version. - Add a harness that follows the runner protocol, and a
Languageentry inrunner/languages.py. - Generate starter code in
backend/localcode/importer/signatures.py, include the language inbuild.py'slangs, add it toLanginservices/models.py, and runmake api-types. - Add it to
LANG_LABEL(web/src/api.ts) andMONACO_LANG(web/src/monaco.ts). - Add runner tests mirroring
test_jvm.py/test_cpp.py.
- Regenerate the test-case exclusion list after a dataset update or a judging change:
make validate-cases(about an hour with three runner replicas), then commitbackend/localcode/data/excluded_cases.json. It also prints two lists to act on: problems whose references differ from the expected answers only in list order (give those a mode inbackend/localcode/judging/answer_modes.pyand re-run them with--only), and problems whose exclusions rest on the references agreeing although none passes half the suite (check that those inputs really break the problem's constraints). - Check the answer checkers after a dataset update:
make check-checkers. Every checker must accept the dataset's expected answers on every non-excluded case. - Check reference pass rates against a scratch instance:
backend/.venv/bin/python -m localcode.tools.sample_refs -n 100. - Release: move the
Unreleasedsection of CHANGELOG.md under a version heading, tagvX.Y.Z, and publish a GitHub release.