From c7f29b46030911df314a6df508ec060c28d4e8ef Mon Sep 17 00:00:00 2001 From: burinc Date: Mon, 7 Sep 2026 13:44:22 +1000 Subject: [PATCH] docs: honest homepage gallery, doc-drift note, CONTRIBUTING.md Follow-up to #5 (already merged: the README's work-in-progress line and its placeholder-gallery removal). This covers the rest of the same review: - docs/templates/home.html: the hero now leads with the same bold "Work in progress: this has not yet been run on Android hardware" framing as the README, instead of a softer note. The 17-image demo grid is gone entirely, captions and the trailing fps table with it: one of those captures (spirograph) is a literal iPhone screen recording, status bar and all, and the rest are the same raylib-ios origin even where it isn't as visible. The gallery section is now a short paragraph saying so, with a link to raylib-ios's own site for the real captures until this build has Android ones. - docs/check-site.sh: dropped the assertion that the built homepage embeds lorenz.gif and tesseract.gif, since that grid no longer exists. Replaced with a comment on what to restore, and why, once real captures land. Nothing else in the gate depended on the grid. - README.md and the homepage hero both note that Jolt and the libraries this project sits on (raylib-jlt, jolt-lang/nrepl, the pinned raylib revision) are still evolving, so a detail here can go stale between releases, and a version mismatch is worth checking against deps.edn before it's filed as a bug. - Adds CONTRIBUTING.md: an invitation (this is community- and team-built, suggestions and missing-piece reports welcome) plus an etiquette section adapted from Clojure's own community etiquette guide (https://clojure.org/community/etiquette), linked from a new README Contributing section. No image assets deleted, only what the docs and the site homepage show. --- CONTRIBUTING.md | 60 +++++++++++++++++++++ README.md | 13 +++++ docs/check-site.sh | 12 ++--- docs/templates/home.html | 114 +++++++-------------------------------- 4 files changed, 97 insertions(+), 102 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..eafea49 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# Contributing + +This project is built by the community and the team behind it, and we would +love your suggestions for improvement. If something is missing, unclear, or +just plain wrong, please let us know: open an issue for a question or a +gap, and a pull request for anything you have already worked out. + +Two things worth reading first, so a report doesn't retread known ground: + +- `README.md` and `tools/android/RUNBOOK.md` both say, more than once, that + this port has not yet been run on Android hardware. A report that only + reproduces "the docs describe something no real device has confirmed" is + already known. +- Jolt itself, and the libraries this project sits on (raylib-jlt, + jolt-lang/nrepl, the pinned raylib revision), are still evolving. Check + the version pins in `deps.edn` against what you actually have installed + before filing a mismatch as a bug here. + +## Etiquette + +Adapted from the Clojure community's own +[etiquette guide](https://clojure.org/community/etiquette), since it says +what we would want to say ourselves and says it well. + +Issues, pull requests and discussion here are for people who make things. +Most messages should have one of these forms: + +- I made something. Here is my contribution. +- I am trying to use this and having trouble, please help. +- I can help you with that. +- I am trying to build something on top of this and having trouble, please + help. +- I can help you build something. + +They are not the place for opinion pieces or diatribes, and not the place +for advocacy about what "ought" to be built. If you think something ought +to exist, the fastest way to find out is to build it and send a pull +request. Otherwise, respect that other people get to choose what they do +with their time. + +Disagreements about how something has been, or will be, done should take +the form of technical arguments. A technical argument that gets, and +gives, respect: + +- Keeps it short. +- Sticks to the facts. +- Uses logic. +- Leaves people out of it. +- Avoids rhetorical devices: superfluous or opinion-laden adjectives, + claims to speak for the community or that everyone agrees with you, + threats of what will happen unless things go your way, any flavour of + "the sky is falling." + +If you are not the one doing the work, restrict your input to short +technical arguments supporting your position. If someone has already made +your point, a "+1" is enough, and keeping posts short is worth doing on +its own. + +Ignoring these guidelines costs the time of the people who make things, +which is worth caring about if you intend to be one of them. diff --git a/README.md b/README.md index 105b0ba..e5e8d0e 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,12 @@ RUNBOOK says the same thing at the top, for the same reason: what follows below is read off the pinned raylib source and the code in this tree, not measured on a phone. +These docs are also a moving target. Jolt and the libraries this project +sits on (raylib-jlt, jolt-lang/nrepl, the pinned raylib revision) are still +evolving, so a detail here can go stale between one release and the next. +Check the version pins in `deps.edn` against what you actually have +installed before assuming a mismatch is a bug in this repository. + What exists today: a gallery of seventeen scenes in four categories, each one a pure `.cljc` simulation, under an Android owner loop of about thirty lines. The scene contract is tested on the build host (`jolt test`, no device @@ -357,6 +363,13 @@ every frame — `raylib.flappy` and `raylib.touch` — were always fine. both offsets at 0 — so the screen is the native window in physical pixels and nothing scales. Ask for a size instead and raylib letterboxes into it. +## Contributing + +This is built by the community and the team behind it, and a suggestion for +improvement or a "this is missing" is exactly the kind of thing to open an +issue about. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the etiquette we +ask discussion and pull requests to follow, adapted from Clojure's own. + ## Licence [zlib](LICENSE), matching diff --git a/docs/check-site.sh b/docs/check-site.sh index d59b886..e56736b 100755 --- a/docs/check-site.sh +++ b/docs/check-site.sh @@ -41,12 +41,12 @@ for page in performance-on-a-phone porting-an-example; do test -f "$out/guide/$page.html" || { echo "missing guide page: $page"; exit 1; } done -# The homepage links every scene, and the two most recent are the ones most -# likely to be forgotten when the grid is edited. -for img in lorenz.gif tesseract.gif; do - grep -q "$img" "$out/index.html" || { echo "homepage does not show $img"; exit 1; } - test -f "$out/images/$img" || { echo "missing image: $img"; exit 1; } -done +# The homepage used to embed a scene grid, and this checked the two most +# recent scenes stayed in it when the grid was edited. The grid is gone for +# now: every one of those captures was a real raylib-ios screen recording, +# not an Android one, and the homepage says so instead of showing them. Bring +# this check back, naming whichever scenes are newest at the time, once the +# grid comes back with real Android captures. # The base path has to reach the emitted HTML, not just site.edn. Getting this # wrong is the failure mode the engine's own README calls out: the pages render diff --git a/docs/templates/home.html b/docs/templates/home.html index c47d4bc..de6f0f6 100644 --- a/docs/templates/home.html +++ b/docs/templates/home.html @@ -13,9 +13,15 @@

raylib on an Android phone, from Clojure

dependencies.

- The captures below come off the sibling build this was ported from; - the scenes are the same files. This host has not yet met an Android - device, and no frame time here was measured on one. + Work in progress: this has not yet been run on Android + hardware. What follows is read off the pinned raylib source + and the code in this tree, not measured on a phone. +

+

+ These docs are also a moving target: Jolt and the libraries this + project sits on (raylib-jlt, jolt-lang/nrepl, the pinned raylib + revision) are still evolving, so a detail here can go stale between + one release and the next.

Read the guide @@ -127,101 +133,17 @@

The gallery

itself. The other fourteen are ports from raylib-jlt.

-
- - A hypotrochoid drawing itself in rainbow lines -
spirograph · 55 fps
- - - A stroke mirrored into six-fold symmetry -
kaleidoscope · 58 fps
- - - Rockets bursting into falling sparks -
fireworks · 58 fps
- - - Forty-five boids flocking -
boids · 52 fps
- - - Flappy Bird, flapped by a loop inside the app -
flappy-bird · unchanged from Android
- - - A chaotic double pendulum tracing its path -
double-pendulum · 59 fps
- - - Fourier epicycles drawing a square wave -
fourier-epicycles · 59 fps
- - - A binary fractal tree swaying -
fractal-tree · 59 fps
- - - A starfield flying toward the viewer -
starfield · 58 fps
- - - A Hilbert space-filling curve -
hilbert-curve · 1023 lines at 60 fps
- - - An L-system plant growing segment by segment -
l-system · 1488 segments at 59 fps
- - - Particles following a drifting flow field -
flow-field · 54 fps, tuned down from 32
- - - The Lorenz attractor, camera orbiting a 450-point trail -
lorenz · 58 fps, and where the budget rule broke
- - - A rotating 4D hypercube projected to the screen -
tesseract · 32 edges, the cheapest scene here
- - - A Penrose P3 tiling by deflation -
penrose · 57 fps
- - - Two eyes whose pupils follow a finger -
following-eyes · unchanged from Android
- - - A fading trail following the primary pointer -
touch-trail · unchanged from Android
- - - The category screen -
the gallery · two levels
- -

- generative 6 · fractals 3 · toys 5 · games 1 · three of them byte-identical to the - Android originals. Every capture and every frame rate on this page - came off the sibling build this was ported from, not off an Android - device — the scenes are the same files, so they are what to compare - against rather than what to quote. Nobody touched the device for any of - them: Flappy Bird is flapped by a loop running inside the app, started - from the nREPL. + There are no screenshots here yet, for the same reason there are none + in the README: nothing has run on Android to photograph honestly. Every + capture that stood here before was a real screen recording, phone + status bar and all, but of raylib-ios, the + sibling project this tree was ported from, not of this build. That + project's own site has the captures and frame rates for what the + scenes draw, and this section gets real Android ones once this build + has actually met a phone.

- - - - - - - - - - - -
ScenePer framefps
Kaleidoscope708 lines58
Fireworks~120 circles58
Penrose340 triangles, ~2400 FFI calls57
Spirograph~1000 lines55
Boids2025 distance tests52
Flappy Bird, Following Eyes, Touch Trailbyte-identical from Android58