From 7d64a617d41279da6257a1b7084e7805caa2dd6b Mon Sep 17 00:00:00 2001 From: Orkuncakilkaya Date: Sun, 30 Aug 2026 16:46:30 +0300 Subject: [PATCH] docs: add CONTRIBUTING, code of conduct, and Forgejo templates Contributor onboarding for the self-hosted toolchain (issue #37): - `CONTRIBUTING.md`: prerequisites, the bootstrap one-liner, the dev loop (`bin/x reseed` -> `bin/x bootstrap-cfree` -> `bin/x test`), stdlib-addition guidance, and the code/commit conventions (Conventional Commits, ludic-fmt, one-job-per-file, Ludic-not-C/Python/JS for new tooling). - `.forgejo/issue_template/`: bug, proposal, and cleanup/DX templates. - `.forgejo/pull_request_template.md`: a checklist covering tests, the bootstrap fixpoint, formatting, docs/inventory, and commit style. - `.forgejo/CODEOWNERS` and a short `CODE_OF_CONDUCT.md`. Closes #37 Co-Authored-By: Claude Opus 4.8 --- .forgejo/CODEOWNERS | 4 ++ .forgejo/issue_template/bug.md | 34 ++++++++++ .forgejo/issue_template/cleanup.md | 21 +++++++ .forgejo/issue_template/proposal.md | 31 +++++++++ .forgejo/pull_request_template.md | 24 +++++++ CODE_OF_CONDUCT.md | 27 ++++++++ CONTRIBUTING.md | 97 +++++++++++++++++++++++++++++ 7 files changed, 238 insertions(+) create mode 100644 .forgejo/CODEOWNERS create mode 100644 .forgejo/issue_template/bug.md create mode 100644 .forgejo/issue_template/cleanup.md create mode 100644 .forgejo/issue_template/proposal.md create mode 100644 .forgejo/pull_request_template.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/.forgejo/CODEOWNERS b/.forgejo/CODEOWNERS new file mode 100644 index 00000000..3ca8df0e --- /dev/null +++ b/.forgejo/CODEOWNERS @@ -0,0 +1,4 @@ +# Default owner for everything in the repo. Forgejo requests review from these +# owners on matching pull requests. See: +# https://forgejo.org/docs/latest/user/code-owners/ +* @orkun diff --git a/.forgejo/issue_template/bug.md b/.forgejo/issue_template/bug.md new file mode 100644 index 00000000..e5100d79 --- /dev/null +++ b/.forgejo/issue_template/bug.md @@ -0,0 +1,34 @@ +--- +name: "Bug report" +about: "Something in the compiler, runtime, or tooling behaves incorrectly" +title: "bug: " +labels: + - bug +--- + +## What happened + + + +## Minimal reproduction + + + +```ludic +``` + +## Expected vs actual + +- **Expected:** +- **Actual:** + +## Environment + +- Command used (e.g. `bin/x app foo.ludic --headless`): +- Target (native macOS / headless / web-wasm): +- Commit (`git rev-parse --short HEAD`): +- OS / arch: + +## Notes + + diff --git a/.forgejo/issue_template/cleanup.md b/.forgejo/issue_template/cleanup.md new file mode 100644 index 00000000..08805997 --- /dev/null +++ b/.forgejo/issue_template/cleanup.md @@ -0,0 +1,21 @@ +--- +name: "Cleanup / DX" +about: "Repo hygiene, tooling, docs, or developer-experience improvements" +title: "" +labels: + - cleanup + - dx +--- + +## Problem + + + +## Proposal + + + +## Acceptance criteria + +- [ ] +- [ ] diff --git a/.forgejo/issue_template/proposal.md b/.forgejo/issue_template/proposal.md new file mode 100644 index 00000000..b3d96a26 --- /dev/null +++ b/.forgejo/issue_template/proposal.md @@ -0,0 +1,31 @@ +--- +name: "Proposal" +about: "Propose new language, stdlib, or runtime surface" +title: "Proposal: " +labels: + - proposal +--- + +## Summary + + + +## Motivation + + + +## Proposed surface + + + +```ludic +``` + +## Determinism & backends + + + +## Alternatives considered + +## Open questions diff --git a/.forgejo/pull_request_template.md b/.forgejo/pull_request_template.md new file mode 100644 index 00000000..7202e9f3 --- /dev/null +++ b/.forgejo/pull_request_template.md @@ -0,0 +1,24 @@ + + +## What & why + + + +Closes # + +## Checklist + +- [ ] `bin/x test` passes. +- [ ] For compiler/runtime changes: `bin/x reseed && bin/x bootstrap-cfree` + still reaches the self-hosting fixpoint with no C compiler in the loop. +- [ ] `ludic-fmt` leaves the touched files unchanged (2-space, LF, UTF-8). +- [ ] New/changed stdlib symbols are documented under `docs/language/**` and + registered in `tools/docgen/inventory.json` + (`python3 tools/docgen/check.py` passes). +- [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org). +- [ ] No new C / Python / JS in tooling (Ludic only), and no generated + artifacts committed outside `build/` / `bin/`. + +## Notes for reviewers + + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..94db0998 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,27 @@ +# Code of Conduct + +## Our standard + +Ludic is a small, focused project. Everyone taking part — filing issues, +proposing changes, reviewing, or discussing — is expected to keep it a +respectful, harassment-free place to collaborate, regardless of background or +experience level. + +**Do:** be direct and kind, critique code rather than people, assume good +faith, and keep discussion technical and on-topic. + +**Don't:** harass, insult, demean, or discriminate; post others' private +information; or derail threads with personal attacks. + +## Scope + +This applies to all project spaces — the issue tracker, pull requests, and any +official channels — and to public spaces when someone is representing the +project. + +## Enforcement + +Report unacceptable behaviour to the maintainer at **orkun@workshopsoft.io**. +Reports are handled confidentially. Maintainers may edit or remove contributions +that violate this code, and may temporarily or permanently bar anyone whose +behaviour is judged harmful. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..0e914cf1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# Contributing to Ludic + +Thanks for your interest in Ludic — an AoT-**compiled** game language with an +ECS core, a deterministic fixed-point runtime, and a native 2D backend. This +guide covers the unusual bit: Ludic is **self-hosted**, so the compiler, the +runtime, and the tooling are all written in Ludic and built by Ludic. + +## Prerequisites + +- `clang` (or another C compiler) — used **once** to assemble the checked-in + LLVM-IR seed into the first `ludicc`, and thereafter only to assemble IR and + link. No C is generated in a build. +- LLVM (for the web/wasm target: `brew install llvm lld`). +- macOS for the windowed Cocoa backend; headless PPM rendering works anywhere. + +## First build (bootstrap) + +From a clean checkout, one line lifts the toolchain off the seed: + +```bash +clang selfhost/ludicc.seed.ll -o bin/ludicc && bin/ludicc tools/x/main.ludic -o bin/x +``` + +That gives you `bin/x`, the Ludic task runner that replaces every build/test +shell script in the repo. From then on it builds everything — including itself: + +```bash +bin/x build # rebuild the whole toolchain into bin/ (ludicc, ludic, x, ludic-fmt, ludic-lsp) +bin/x help # list every command +``` + +Always run `x` from the repository root, so `assets/` and `selfhost/` resolve. + +## The development loop + +When you change the compiler or runtime, prove the self-hosting fixpoint still +holds before you push: + +```bash +bin/x reseed # regenerate selfhost/ludicc.seed.ll after a compiler change +bin/x bootstrap-cfree # rebuild the compiler from the seed with NO C compiler in the loop +bin/x test # the full regression suite +``` + +Other useful targets: + +```bash +bin/x app [--headless] # compile a program to a native app in build/ +bin/x selfhost-test # correctness + bootstrap fixpoints +bin/x test-tools # the editor-toolchain suite (ludic-fmt, ludic-lsp) +bin/x clean # remove build/, out.ppm and stray artifacts +``` + +## Adding to the standard library + +The stdlib lives in the runtime (`runtime/`) and is surfaced as namespaces +(`Math.*`, `Crypto.*`, `DateTime.*`, `Screen.*`, …). When you add a symbol: + +1. Implement it in the runtime / emitter as appropriate. +2. Document it: add one Markdown file per symbol under `docs/language//` + and register its id in `tools/docgen/inventory.json`. Each documented + namespace gets exactly **one** directory (the docs check enforces this). +3. Add or extend an example under `examples/` and a case in the test suite. +4. Run `python3 tools/docgen/gen.py && python3 tools/docgen/check.py` — the + check fails if any inventory symbol lacks a page or is still seed text. + +## Conventions + +- **Commits:** [Conventional Commits](https://www.conventionalcommits.org) — + `type(scope): summary`, e.g. `feat(stdlib): …`, `fix(emit): …`, + `ci(docs): …`, `docs(readme): …`. Keep the summary imperative and under ~72 + chars. +- **Formatting:** `ludic-fmt` is the source of truth (2-space indent, LF, UTF-8); + the repo `.editorconfig` mirrors it. Run `bin/ludic-fmt` on files you touch. +- **Code structure:** one job per file. Split large files by concern into + subfolders rather than growing a single 500+-line module (see how `selfhost/` + and `runtime/` are organised). +- **Language of the toolchain:** new runtime and tooling are written in **Ludic**, + not C, Python, or JS. The only non-Ludic pieces are the LLVM-IR seed + (`selfhost/ludicc.seed.ll`), the hand-written `runtime/native/cocoa.ll` / + `runtime/web/wasm.ll` shims, and the legacy Python docgen (being ported). + +## Pull requests + +- Base your branch on `main`. +- Ensure `bin/x test` (and `bin/x bootstrap-cfree` for compiler/runtime changes) + pass, and that `ludic-fmt` leaves your files unchanged. +- Fill in the PR template checklist. Reference the issue you close with + `Closes #NN` in the description or a commit message. + +## Reporting issues + +Use the templates under [`.forgejo/issue_template/`](.forgejo/issue_template): +a **bug report**, a **proposal** (new stdlib/language surface), or a +**cleanup/DX** task. Choose the one that fits and fill in the sections. + +By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).