Skip to content

Commit 89f236d

Browse files
ewowiewowi
committed
Update development docs and github issues
1 parent cd01cb1 commit 89f236d

9 files changed

Lines changed: 309 additions & 204 deletions

File tree

‎CLAUDE.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,3 +169,13 @@ Supplementary guidance for AI assistants lives in `/misc/instructions/`:
169169
- **`MoonLight.md`** — project philosophy, architectural goals, future roadmap, and broader context not covered above.
170170
- **`GEMINI.md`** — structural overview of the upstream [ESP32-sveltekit](https://github.com/theelims/ESP32-sveltekit) repo (services, file layout, key dependencies). Useful when touching upstream-derived code.
171171
- **`svelte.instructions.md`** — Svelte 5 development guidelines. Applies **only** to moonbase-specific frontend files (`src/routes/moonbase/`, `src/lib/components/moonbase/`, `moonbase_utilities.ts`, `moonbase_models.ts`). Do not apply runes patterns or reformatting to upstream files.
172+
173+
### Loading These Documents
174+
175+
To optimize token usage, these additional reference documents are **not loaded by default**. Load them explicitly only when:
176+
177+
- Working on architectural decisions or long-term planning (load `MoonLight.md`)
178+
- Modifying upstream-derived code or understanding ESP32-sveltekit patterns (load `GEMINI.md`)
179+
- Building or modifying Svelte frontend components (load `svelte.instructions.md`)
180+
181+
Unless you receive explicit instructions to reference these files, AI assistants should not load them to conserve context and improve efficiency.

ESP32-sveltekit.code-workspace renamed to MoonLight.code-workspace

File renamed without changes.

‎docs/develop/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../CLAUDE.md

‎docs/develop/development.md‎

Lines changed: 149 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,128 +1,192 @@
11

22
# Development
33

4-
## Summary
4+
See [Standards and Guidelines](standardsguidelines.md) for coding rules, code style, and guidance on using AI tools (optional) before contributing.
55

6-
* Create a branch
7-
* Make changes
8-
* Document your change
9-
* Submit a pull request
6+
---
107

11-
[Standards and Guidelines](https://moonmodules.org/MoonLight/develop/standardsguidelines/). Check before submitting a request!
8+
## Pull Requests
129

13-
## Create a branch
10+
Complete workflow: create branch → create PR → make changes → merge.
1411

15-
* Want to make changes: fork the repo (see installation) and submit pull requests, see [creating-a-pull-request-from-a-fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork):
12+
Found a bug while developing? See [Reporting Issues](../moonlight/overview.md#reporting-issues) for how to document and report it properly.
1613

17-
* Only branch from the main branch! Press Branches, press New Branch, give it a name e.g. background-script and press Create new Branch, click on background-script
18-
19-
<img width="90" src="https://github.com/user-attachments/assets/588d0854-bac1-4b70-8931-ba6db4c94248" />
14+
### Creating a PR
2015

21-
## Make changes
16+
**Step 1: Create a feature branch** from `main` — always target `main`.
2217

23-
### Front-end (UI)
18+
**Step 2: Make your first commit**
2419

25-
* interface folder
26-
* interface/src/routes/moonbase for MoonBase and MoonLight (modules)
27-
* see [Prepare for development](https://moonmodules.org/MoonLight/develop/installation/#prepare-for-development) about nodejs, npm install
20+
For complex tasks, optionally create an implementation plan in [Work in progress](workinprogress.md):
2821

29-
```markdown
30-
npm install
31-
npm run dev
22+
- **Option A (for simpler tasks)**: Skip planning, or write a brief plan yourself and commit to `workinprogress.md`.
23+
24+
- **Option B (if you prefer)**: If you'd like help planning, you can ask an AI agent (Claude Code or Mistral) to draft a detailed plan. The result is an updated `workinprogress.md` — commit that to your branch before writing code.
25+
26+
**Good times to ask an AI for a plan:**
27+
- Adding a new module or feature area
28+
- Cross-cutting refactors affecting multiple files
29+
- Complex architectural decisions
30+
31+
**Prompt template (if using AI):**
32+
33+
```
34+
Create a detailed implementation plan for [task description], outlining:
35+
- The steps involved
36+
- Affected files and modules
37+
- Architectural decisions
38+
- Any risks or edge cases
39+
40+
Add this plan to /docs/develop/workinprogress.md and refer to it in your commits.
41+
Check the Work in Progress document to see current plans, their status, and phases.
42+
```
43+
44+
Make changes to the code base, see [Make changes](#make-changes)
45+
46+
**Step 3: Open the PR**
47+
48+
1. Push the first commit to your branch
49+
2. Create a Pull Request with an **empty description** — CodeRabbit will analyze your commits and auto-generate one
50+
3. Review CodeRabbit's description — optionally edit it before requesting review
51+
52+
### Updating an open PR
53+
54+
Push additional commits to your branch — GitHub keeps the PR up-to-date automatically.
55+
56+
!!! warning "Do not force-push while your PR is open"
57+
Force-pushing causes review comments to disappear and has other subtle side effects on the repository history.
58+
59+
See [Make changes](#make-changes) for how to edit frontend/backend code, format, and commit.
60+
61+
**If you'd like to use AI for code changes:**
62+
63+
If you choose to use Claude Code or Mistral Vibe, see [AI Context for contributions](standardsguidelines.md#ai-context-for-contributions) for tips on providing the right context to get helpful results.
64+
65+
**Address feedback:**
66+
67+
1. **CodeRabbit's recommendations** — address in subsequent commits
68+
- Use icons in commit title/description to identify the source: 🐰 (CodeRabbit), ✴️ (Claude), 🐱 (Mistral Vibe)
69+
- Example: `🐰 issues solved by ✴️` (CodeRabbit issues fixed by Claude Code)
70+
- CodeRabbit provides [ready-to-use prompts for AI agents](standardsguidelines.md#using-coderabbit-s-ai-prompts) if you'd like help addressing its recommendations
71+
- Commit description: if you use AI to fix issues, you can use its summary — it provides a clear summary of the changes
72+
2. **Code review feedback** — address per reviewer comments
73+
3. **Ensure docs are updated** in your commits, AI can help here.
74+
75+
### Merging a PR
76+
77+
**Keep PRs moving** — target **a week or less** from opening to merge. Stale PRs slow down development and cause conflicts.
78+
79+
Before merging:
80+
81+
1. Ensure all documentation is updated
82+
2. Ask CodeRabbit for a final review:
83+
84+
```
85+
@coderabbitai, I am about to merge this PR. Please produce three outputs:
86+
87+
1. **PR review** — in-depth review of all commits: a concise summary of what changed
88+
and why, a merge recommendation, and a prioritised list of follow-up actions.
89+
For the most urgent items (blockers or high-risk changes), include a ready-to-paste
90+
prompt that a Claude Code agent can execute immediately before merge.
91+
92+
2. **End-user docs prompt** — a ready-to-paste prompt for a Claude Code agent to update
93+
`/docs`. Rules: only describe usage implications (what changed for the user);
94+
no internals, no code, no architecture; check existing pages before adding —
95+
update in place rather than duplicating; keep additions compact and user-friendly.
96+
97+
3. **Developer docs prompt** — a ready-to-paste prompt for a Claude Code agent to update
98+
`/docs/develop`. Rules: target contributors, not end users; be concise — if the
99+
detail is already in the code or commit messages, do not repeat it; focus on
100+
decisions, patterns, and guidance that are not obvious from reading the source.
32101
```
33102

34-
* see [Troubleshooting](https://moonmodules.org/MoonLight/develop/installation/#troubleshooting) about WWWData.h
103+
After merging, **delete the feature branch** — it keeps the repository clean and is always recoverable via git if needed.
35104

36-
### Back-end (Server)
105+
---
37106

38-
There are 3 levels to add functionality:
107+
## Make changes
39108

40-
* **Standard ESP32-Sveltekit code**, e.g. Connections, Wifi and System. MoonBase files are also made using standard SvelteKit as examples but contain a few components used in MoonLight modules. Might be rewritten as a MoonLight Module in the future.
41-
* lib folder for Sveltekit back-end
42-
* Read the [ESP32 Sveltekit docs](https://moonmodules.org/MoonLight/esp32sveltekit/)
43-
* [MoonLight Modules](https://moonmodules.org/MoonLight/moonbase/modules/) e.g. Lights Control, Effects, Info, Channels. They are subclasses of Modules.h/cpp and implement setupDefinition, onUpdate and optional loop. New modules need to be defined in main.cpp and added to menu.svelte. All further UI is generated by Module.svelte.
44-
* src folder for MoonBase and MoonLight back-end
45-
* **MoonLight Nodes**: the easiest and recommended way. See Effects.h, Layouts.h, Modifiers.h and Drivers.h for examples. They match closest WLED usermods. Each node has controls, a setup and a loop and can be switched on and off. For specific purposes hasOnLayout() and hasModifier() can return true.
46-
* src/MoonLight/nodes
109+
Instructions for editing and committing code (used while [updating an open PR](#updating-an-open-pr)).
47110

48-
### Steps
111+
### Frontend (UI)
49112

50-
* Go to the file(s) you want to change press edit and make the changes.
51-
* ☑️ and ➡️ to build and or upload
52-
* Changes made to the UI are not always visible in the browser, clear the browser cache to see latest UI (see [connect to MoonLight](https://moonmodules.org/MoonLight/gettingstarted/installer/#connect-moonlight)).
53-
* MoonLight uses clang-format for c/c++ code and prettier for Svelte, javascript etc. Format your code before submitting! (right-click Format Document on each page you change)
54-
* Press Commit Changes..., enter a commit message and an extended description, Press Commit Changes
113+
- Files live in `interface/src/routes/moonbase/` (MoonBase and MoonLight modules)
114+
- See [Prepare for development](installation.md#prepare-for-development) for Node.js setup
55115

56-
## Document your changes
116+
```bash
117+
npm install
118+
npm run dev
119+
```
57120

58-
See [Documentation](https://moonmodules.org/MoonLight/develop/documentation/)
121+
See [Troubleshooting](installation.md#troubleshooting) for common issues.
59122

60-
## Submit a pull request
123+
**UI development server:** Deploy backend to an ESP32 and proxy API calls through the local dev server — no reflashing needed for UI changes. After setup, open [localhost:5173](http://localhost:5173/).
124+
See [Setup Proxy for Development](installation.md#prepare-for-development) for details.
61125

62-
* Go back to the homepage of your fork [myfork/MoonLight](https://github.com/ewowi/MoonLight). There is a message inviting to create a Pull Request. Press Compare & pull request.
63-
64-
<img width="350" src="https://github.com/user-attachments/assets/410aa517-99eb-4907-b1a3-db7f38abb194" />
65-
66-
* Add a title and Description to the Pull Request and press Create Pull Request
67-
68-
* The upstream MoonLight repo can now process this PR
126+
!!! tip "Node.js"
127+
If Node.js is not installed: see [Prepare for development](installation.md#prepare-for-development).
69128

70-
## Additional info
129+
### Backend (Server)
71130

72-
### Emoji coding
131+
Three levels to add functionality:
73132

74-
* Serial Log shows which code is from which library using emoji:
133+
| Level | Where | Use when |
134+
|-------|-------|----------|
135+
| **ESP32-SvelteKit standard** | `lib/` | Connections, WiFi, System — do not modify |
136+
| **[MoonBase Modules](../moonbase/overview.md)** | `src/` | New modules: subclass `Module`, implement `setupDefinition`, `onUpdate`, optional `loop` |
137+
| **[MoonLight Nodes](nodes.md)** | `src/MoonLight/nodes/` | New effects, layouts, modifiers, drivers — easiest approach, closest to WLED usermods |
75138

76-
<img width="500" src="https://github.com/user-attachments/assets/9ac673d3-6303-40ee-b2a0-26a0befbda01" />
139+
### Steps
77140

78-
* 🐼: ESP-SvelteKit
79-
* 🔮: PsychicHTTP
80-
* 🐸: Live Scripts
81-
* 🌙: MoonBase
82-
* 💫: MoonLight
83-
🌙 and 💫 is also used in code comments of ESP32-SvelteKit to show where changes to upstream have been made.
84-
* The following ESP32-SvelteKit features have been switched off in the default builts (they can be switched on if you want to use them, see [features.ini](https://github.com/MoonModules/MoonLight/blob/main/features.ini))
85-
* -D FT_SECURITY=0
86-
* -D FT_SLEEP=0
87-
* ~~-D FT_BATTERY=1~~ enabled!
141+
1. Edit the file(s), build with ☑️ and/or upload with ➡️
142+
2. Format code before committing: right-click → **Format Document** (clang-format for C/C++, Prettier for frontend)
143+
3. Clear browser cache if UI changes are not visible
144+
4. Commit with a descriptive message and extended description
145+
5. Update documentation in `/docs` alongside code changes
88146

89-
### UI development server
147+
---
90148

91-
To ease the front-end development you can deploy the back-end code on an ESP32 board and pass the websocket and REST API calls through the development server's proxy running on your computer.
149+
## Additional reference
92150

93-
This very much speeds up UI development, as no flashing to the ESP32 is required to test updated UI. Saving a UI file is enough to see the results.
151+
### Emoji coding
94152

95-
See [Setup Proxy for Development](https://moonmodules.org/MoonLight/gettingstarted/#setup-proxy-for-development) and [development-server](https://moonmodules.org/MoonLight/gettingstarted/#development-server) how to setup.
153+
Serial log shows which library the output is from:
96154

97-
!!! tip "nodejs"
98-
if nodejs is not installed yet: see [Prepare for development](https://moonmodules.org/MoonLight/develop/installation/#prepare-for-development) to install nodejs
155+
| Emoji | Library |
156+
|-------|---------|
157+
| 🐼 | ESP-SvelteKit |
158+
| 🔮 | PsychicHTTP |
159+
| 🐸 | Live Scripts |
160+
| 🌙 | MoonBase |
161+
| 💫 | MoonLight |
99162

100-
After configuring the development server, a local webserver starts on [localhost:5173](http://localhost:5173/).
163+
`🌙` and `💫` are also used in code comments to mark changes to upstream ESP32-SvelteKit files.
101164

102165
### Release and merged firmware binaries
103166

104-
Firmware binaries come in 2 flavours: including boot and partition (merged) and MoonLight code only (release). They are stored in the build folder of the MoonLight repo and updated each time a build or upload (☑️ or ➡️) is done. Subfolder merged contains the first type, release the second type.
167+
Firmware binaries come in two flavours:
168+
169+
| Type | Folder | Used by | Flash offset |
170+
|------|--------|---------|--------------|
171+
| Merged (boot + partition + firmware) | `build/merged/` | [MoonLight Installer](../gettingstarted/installer.md) | `0x0` |
172+
| Release (firmware only) | `build/release/` | [System update](../system/update.md) (OTA) · [GitHub releases](https://github.com/MoonModules/MoonLight/releases) | `0x10000` |
105173

106-
* Merged bins are used by the [MoonLight Installer](https://moonmodules.org/MoonLight/gettingstarted/installer/), release bins by the [System update](https://moonmodules.org/MoonLight/system/update/) module (OTA). System update uses the bins stored in [GitHub releases](https://github.com/MoonModules/MoonLight/releases).
107-
* Merged bins starts flashing on address 0x0, release bins on address 0x10000.
108-
* All MoonLight partition schemes have a firmware size of 3MB. Smaller devices (e.g. ESP32-D0) have no OTA partition. System update is possible in this situation, but there is no fallback if update fails (need to flash using USB in that case) 🚧
174+
All partition schemes have a 3 MB firmware size. ESP32-D0 has no OTA partition — system update works but has no fallback if it fails (flash via USB in that case).
109175

110-
!!! tip "flash firmware using esptool"
111-
* [>_] in the statusbar of vscode
112-
```
113-
esptool --port /dev/cu.usbserial-1130 write-flash -b 2000000 0x0 ./build/merged/MoonLight_esp32-s3-n16r8v_0-6-1_webflash.bin
114-
```
115-
* replace port and file to match your setup
116-
* optionally add erase-flash before write-flash
117-
* -b 2000000: Baud rate: lower if too high for your device
118-
* use ./build/release/MoonLight_esp32-s3-n16r8v_0-6-1.bin and address 0x10000 to flash only the MoonLight partition
176+
!!! tip "Flash firmware using esptool"
177+
```bash
178+
esptool --port /dev/cu.usbserial-1130 write-flash -b 2000000 0x0 ./build/merged/MoonLight_esp32-s3-n16r8v_0-6-1_webflash.bin
179+
```
180+
Replace port and filename to match your setup. Optionally add `erase-flash` before `write-flash`. Use `0x10000` and the `build/release/` binary to flash only the MoonLight partition.
119181

120-
### Adding an ESP32 device Definition
182+
### Adding an ESP32 device definition
121183

122-
Before starting, ensure you have the datasheet of your particular chip and ESP32-device confirmed and available. Many modules have near-identical markings that can hide varying hardware.
184+
Before starting, ensure you have the datasheet confirmed. Many modules have near-identical markings that can hide varying hardware.
123185

124-
There are 3 files to consider when making a ESP32-device definition.
186+
Three files to create or modify:
125187

126-
boards/BOARD_NAME.csv
127-
boards/BOARD_NAME.JSON
128-
firmware/BOARD_TYPE_NAME.ini (e.g. esp32dev, esp32-s3), contains different boards
188+
```
189+
boards/BOARD_NAME.csv
190+
boards/BOARD_NAME.json
191+
firmware/BOARD_TYPE_NAME.ini (e.g. esp32dev, esp32-s3 — one file may contain multiple boards)
192+
```

0 commit comments

Comments
 (0)