From 0d44bc9cf0ec09b8f7bccedc5c82339266715c19 Mon Sep 17 00:00:00 2001
From: Abe Pazos <abe@hamoid.com>
Date: Wed, 12 Jun 2024 16:48:02 +0200
Subject: [PATCH] Update CONTRIBUTING.md

---
 CONTRIBUTING.md | 71 +++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 57 insertions(+), 14 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9f20584b..32c812f4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,7 +7,7 @@ Other repositories you can contribute to are the [core OPENRNDR](https://github.
 the [guide](https://github.com/openrndr/openrndr-guide/) and the [template](https://github.com/openrndr/openrndr-template/).
 
 Please read the [general information about contributing to OPENRNDR](https://github.com/openrndr/openrndr/blob/master/CONTRIBUTING.md).
-This document will focus on specific details about the ORX repository.
+This document focuses on specific details about the ORX repository.
 
 ## Overview
 
@@ -18,11 +18,48 @@ There are two types of ORX extras:
 Each orx folder contains a `README.md`, a `build.gradle.kts` file and a `src` folder. 
 Please explore several orx directories to get a feel for how they look like.
 
-Various Gradle tasks take care of updating the README files. 
+Gradle tasks are used to update the list of ORX'es in the root README.md, 
+and to update the list of demos in each ORX'es README.md.
 
-## README.md
+## Folder structure (JVM)
 
-Assuming you are creating an orx called `magic`, the readme file should contain the following:
+```
+orx-magic/
+├── README.md
+├── build.gradle.kts
+└── src/
+    ├── main/
+    │   └── kotlin/
+    │       └── Magic.kt
+    └── demo/
+        └── kotlin/
+            ├── DemoFoo01.kt
+            └── DemoBar01.kt
+```
+
+## Folder structure (multiplatform)
+
+```
+orx-magic/
+├── README.md
+├── build.gradle.kts
+└── src/
+    ├── commonMain/kotlin/
+    │   └── Magic.kt
+    ├── commonTest/kotlin/
+    ├── jsMain/kotlin/
+    ├── jsTest/kotlin/
+    ├── jvmDemo/kotlin/
+    │   ├── DemoFoo01.kt
+    │   └── DemoBar01.kt
+    ├── jvmMain/kotlin/
+    └── jvmTest/kotlin/
+```
+Note that inside `src` only `commonMain` is required.
+
+## ORX README.md
+
+Assuming you are creating an orx called `magic`, the readme should be formatted as follows:
 
 ```
 # orx-magic
@@ -31,7 +68,8 @@ One or more lines including a short description to display on the root README.md
 One or more lines including a short description to display on the root README.md.
 One or more lines including a short description to display on the root README.md.
 
-[Main content describing the usage of orx-magic goes here]
+Main content describing the usage of orx-magic goes here
+...
 
 <!-- __demos__ -->
 ```
@@ -50,7 +88,7 @@ One or more lines including a short description to display on the root README.md
    This is specially useful for orx'es that produce graphical output, but less so for orx'es that interface
    with hardware (like `orx-midi`).
 
-## build.gradle.kts
+## ORX build.gradle.kts
 
 ORX `build.gradle.kts` files declare their dependencies and most follow the same structure. 
 Please explore various build files and find the simplest one that matches your use case. 
@@ -67,17 +105,22 @@ See an [example](https://github.com/openrndr/orx/blob/master/orx-jvm/orx-dnk3/bu
 
 ### Multiplatform
 
-The multiplatform build files can have 4 blocks: `commonMain`, `commonTest`, `jvmTest` and `jvmDemo`. 
-See an [example](https://github.com/openrndr/orx/blob/master/orx-color/build.gradle.kts).
-
-## Source folder
-
-To do.
+The multiplatform build files may have blocks like `commonMain`, `commonTest`, `jvmTest`, `jvmDemo`, etc. to specify the dependencies for each case. See an [example](https://github.com/openrndr/orx/blob/master/orx-color/build.gradle.kts).
 
 ## Demos
 
-To do.
+ORX'es often include a `jvmDemo` folder. This folder should contain small programs demonstrating
+how the ORX can be used. When the build system runs the 
+[`CollectScreenShots`](buildSrc/src/main/kotlin/CollectScreenShots.kt) task, 
+the `SingleScreenshot()` extension will be injected into each program found inside the `jvmDemo`
+folder, then executed. A PNG screenshot is saved and pushed into the [`media`](https://github.com/openrndr/orx/tree/media) brach. Finally, links to those PNG images are inserted into the README.md file of each ORX,
+together with a link to the source code that produced the screenshot.
+
+This serves two purposes: it can be useful for the user to see images of what the ORX can produce,
+while it can also be usefu to detect breaking changes (in case the demo fails to run, or produces a
+blank image).
 
 ## Gradle tasks
 
-To do.
+* `CollectScreenShots`
+* `buildMainReadme`