Development Workflow

This page defines how to use the wiki during feature development, bug fixes, and demo creation. Following this workflow keeps documentation synchronized with the codebase.

Wiki Consultation Table

Before starting a task, consult the relevant wiki pages:

Task Type	Read First	Update After
UI widget work (buttons, dialogs, HUD)	UI-Widget-Patterns, UI-Component-Hierarchy	UI-Widget-Patterns if new pattern
Grid/layer work (rendering, layers, chunks)	Grid-System, Grid-Rendering-Pipeline	Grid-Rendering-Pipeline if behavior changes
Entity behavior (AI, movement, pathfinding)	Entity-Management, Grid-Interaction-Patterns	Entity-Management if API changes
Mouse/keyboard interaction	Input-and-Events, then relevant pattern page	Input-and-Events if new event types
Grid mouse interaction (cell clicks, selection)	Grid-Interaction-Patterns, Input-and-Events	Grid-Interaction-Patterns if new pattern
Performance work (optimization, profiling)	Performance-and-Profiling	Performance-and-Profiling with results
Python binding changes	UI-Component-Hierarchy, Python-Binding-Layer	Both if signatures change
Animation work	Animation-System	Animation-System if new easing/features
Demo creation	Relevant pattern page + component page	Pattern page if demo reveals new technique
New UIDrawable type	UI-Component-Hierarchy, Adding-Python-Bindings	UI-Component-Hierarchy to add new type

Workflow Steps

1. READ (Before Starting)

Open relevant wiki page(s) from the table above
Note current documented behavior and API
Check "Related Issues" section for context
Understand existing patterns before inventing new ones

2. WORK (During Development)

Keep mental or written notes on:

Discrepancies: "Wiki says X but code does Y"
Gaps: "I needed to know Z but it wasn't documented"
Discoveries: "This technique isn't in the patterns page"

3. REFLECT (Before Commit)

Ask yourself:

Does the wiki accurately describe the new/changed behavior?
Did I discover something that should be documented?
Did I invalidate any documented information?
Are there new patterns worth capturing?

4. COMMIT (Push Code)

Reference issue numbers in commit messages (closes #X, addresses #Y)
Granular commits preferred (one concern per commit)

5. UPDATE (After Code Merged)

With appropriate permissions:

Fix any inaccuracies found during step 2
Add new patterns/techniques discovered
Update issue references (mark closed issues)
Update "Last updated" date at bottom of page

What Belongs Where

Content Type	Destination Page
Class properties, methods, signatures	Component pages (UI-Component-Hierarchy, Grid-System, Entity-Management)
"How to build X" with code examples	Pattern pages (UI-Widget-Patterns, Grid-Interaction-Patterns)
Event handler signatures and dispatch	Input-and-Events
Performance metrics and optimization	Performance-and-Profiling
Architecture and design decisions	Relevant system page
Migration from old API	System page, in dedicated "Migration" section
C++ implementation details	System page, with file references

Page Structure Conventions

Each wiki page should include:

Header sections:

Quick Reference (related issues, key files)
Related Pages links

Body:

Conceptual overview first
API reference tables
Code examples (focused snippets)
Common patterns or techniques

Footer:

Related Systems links
Last updated date

For Claude Code Sessions

When working with Claude Code:

Claude should read relevant wiki pages before implementing features
Claude should note documentation gaps during work
After committing code, Claude should propose wiki updates
User approves wiki changes before Claude pushes them

This keeps documentation current without requiring separate documentation passes.

Home - Wiki index
Contributing - Code contribution guidelines
Writing-Tests - Test-driven development workflow

Last updated: 2025-11-29