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 <noreply@anthropic.com>
This commit is contained in:
parent
3bab2d2d4c
commit
7d64a617d4
7 changed files with 238 additions and 0 deletions
4
.forgejo/CODEOWNERS
Normal file
4
.forgejo/CODEOWNERS
Normal file
|
|
@ -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
|
||||||
34
.forgejo/issue_template/bug.md
Normal file
34
.forgejo/issue_template/bug.md
Normal file
|
|
@ -0,0 +1,34 @@
|
||||||
|
---
|
||||||
|
name: "Bug report"
|
||||||
|
about: "Something in the compiler, runtime, or tooling behaves incorrectly"
|
||||||
|
title: "bug: "
|
||||||
|
labels:
|
||||||
|
- bug
|
||||||
|
---
|
||||||
|
|
||||||
|
## What happened
|
||||||
|
|
||||||
|
<!-- A clear description of the incorrect behaviour. -->
|
||||||
|
|
||||||
|
## Minimal reproduction
|
||||||
|
|
||||||
|
<!-- The smallest .ludic program (or command) that triggers it. -->
|
||||||
|
|
||||||
|
```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
|
||||||
|
|
||||||
|
<!-- Stack traces, generated IR, or anything else that helps. -->
|
||||||
21
.forgejo/issue_template/cleanup.md
Normal file
21
.forgejo/issue_template/cleanup.md
Normal file
|
|
@ -0,0 +1,21 @@
|
||||||
|
---
|
||||||
|
name: "Cleanup / DX"
|
||||||
|
about: "Repo hygiene, tooling, docs, or developer-experience improvements"
|
||||||
|
title: ""
|
||||||
|
labels:
|
||||||
|
- cleanup
|
||||||
|
- dx
|
||||||
|
---
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
<!-- What friction or inconsistency exists today? -->
|
||||||
|
|
||||||
|
## Proposal
|
||||||
|
|
||||||
|
<!-- What to change. Keep it scoped and low-risk. -->
|
||||||
|
|
||||||
|
## Acceptance criteria
|
||||||
|
|
||||||
|
- [ ]
|
||||||
|
- [ ]
|
||||||
31
.forgejo/issue_template/proposal.md
Normal file
31
.forgejo/issue_template/proposal.md
Normal file
|
|
@ -0,0 +1,31 @@
|
||||||
|
---
|
||||||
|
name: "Proposal"
|
||||||
|
about: "Propose new language, stdlib, or runtime surface"
|
||||||
|
title: "Proposal: "
|
||||||
|
labels:
|
||||||
|
- proposal
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
<!-- One or two sentences: what should exist that doesn't today. -->
|
||||||
|
|
||||||
|
## Motivation
|
||||||
|
|
||||||
|
<!-- What can't be done cleanly now? Who needs this and why? -->
|
||||||
|
|
||||||
|
## Proposed surface
|
||||||
|
|
||||||
|
<!-- The namespace/API or syntax you propose. Show it in use. -->
|
||||||
|
|
||||||
|
```ludic
|
||||||
|
```
|
||||||
|
|
||||||
|
## Determinism & backends
|
||||||
|
|
||||||
|
<!-- Ludic's runtime is deterministic fixed-point. Does this proposal stay
|
||||||
|
replay-safe? Does it work on native AND web-wasm, or is it host-gated? -->
|
||||||
|
|
||||||
|
## Alternatives considered
|
||||||
|
|
||||||
|
## Open questions
|
||||||
24
.forgejo/pull_request_template.md
Normal file
24
.forgejo/pull_request_template.md
Normal file
|
|
@ -0,0 +1,24 @@
|
||||||
|
<!-- Thanks for contributing to Ludic! Please fill in the checklist below. -->
|
||||||
|
|
||||||
|
## What & why
|
||||||
|
|
||||||
|
<!-- What does this change and why? Link the issue: Closes #NN -->
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
<!-- Anything reviewers should look at closely, or follow-ups deferred. -->
|
||||||
27
CODE_OF_CONDUCT.md
Normal file
27
CODE_OF_CONDUCT.md
Normal file
|
|
@ -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.
|
||||||
97
CONTRIBUTING.md
Normal file
97
CONTRIBUTING.md
Normal file
|
|
@ -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 <file.ludic> [--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/<namespace>/`
|
||||||
|
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).
|
||||||
Loading…
Add table
Add a link
Reference in a new issue