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.
-
- 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.
-
-
- | Scene | Per frame | fps |
|---|
-
- | Kaleidoscope | 708 lines | 58 |
- | Fireworks | ~120 circles | 58 |
- | Penrose | 340 triangles, ~2400 FFI calls | 57 |
- | Spirograph | ~1000 lines | 55 |
- | Boids | 2025 distance tests | 52 |
- | Flappy Bird, Following Eyes, Touch Trail | byte-identical from Android | 58 |
-
-
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
-