From e41f83a5b3bd747f375c8586d36763677fbba1d1 Mon Sep 17 00:00:00 2001 From: John McCardle Date: Sat, 25 Oct 2025 20:54:55 -0400 Subject: [PATCH] docs: Complete wiki migration and issue labeling system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit completes a comprehensive documentation migration initiative that transforms McRogueFace's documentation from scattered markdown files into a structured, navigable wiki with systematic issue organization. ## Wiki Content Created (20 pages) **Navigation & Indices:** - Home page with 3 entry points (by system, use-case, workflow) - Design Proposals index - Issue Roadmap (46 issues organized by tier/system) **System Documentation (5 pages):** - Grid System (3-layer architecture: Visual/World/Perspective) - Animation System (property-based, 24+ easing functions) - Python Binding System (C++/Python integration patterns) - UI Component Hierarchy (UIDrawable inheritance tree) - Performance and Profiling (ScopedTimer, F3 overlay) **Workflow Guides (3 pages):** - Adding Python Bindings (step-by-step tutorial) - Performance Optimization Workflow (profile → optimize → verify) - Writing Tests (direct execution vs game loop tests) **Use-Case Documentation (5 pages):** - Entity Management - Rendering - AI and Pathfinding - Input and Events - Procedural Generation **Grid System Deep Dives (3 pages):** - Grid Rendering Pipeline (4-stage process) - Grid-TCOD Integration (FOV, pathfinding) - Grid Entity Lifecycle (5 states, memory management) **Strategic Documentation (2 pages):** - Proposal: Next-Gen Grid-Entity System (consolidated from 3 files) - Strategic Direction (extracted from FINAL_RECOMMENDATIONS.md) ## Issue Organization System Created 14 new labels across 3 orthogonal dimensions: **System Labels (8):** - system:grid, system:animation, system:python-binding - system:ui-hierarchy, system:performance, system:rendering - system:input, system:documentation **Priority Labels (3):** - priority:tier1-active (18 issues) - Critical path to v1.0 - priority:tier2-foundation (11 issues) - Important but not blocking - priority:tier3-future (17 issues) - Deferred until after v1.0 **Workflow Labels (3):** - workflow:blocked - Waiting on dependencies - workflow:needs-benchmark - Needs performance testing - workflow:needs-documentation - Needs docs before/after implementation All 46 open issues now labeled with appropriate system/priority/workflow tags. ## Documentation Updates **README.md:** - Updated Documentation section to reference Gitea wiki - Added key wiki page links (Home, Grid System, Python Binding, etc.) - Updated Contributing section with issue tracking information - Documented label taxonomy and Issue Roadmap **Analysis Files:** - Moved 17 completed analysis files to .archive/ directory: - EVAL_*.md (5 files) - Strategic analysis - TOPICS_*.md (4 files) - Task analysis - NEXT_GEN_GRIDS_ENTITIES_*.md (3 files) - Design proposals - FINAL_RECOMMENDATIONS.md, MASTER_TASK_SCHEDULE.md - PROJECT_THEMES_ANALYSIS.md, ANIMATION_FIX_IMPLEMENTATION.md - compass_artifact_*.md - Research artifacts ## Benefits This migration provides: 1. **Agent-friendly documentation** - Structured for LLM context management 2. **Multiple navigation paths** - By system, use-case, or workflow 3. **Dense cross-referencing** - Wiki pages link to related content 4. **Systematic issue organization** - Filterable by system AND priority 5. **Living documentation** - Wiki can evolve with the codebase 6. **Clear development priorities** - Tier 1/2/3 system guides focus Wiki URL: https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 6210792..9d74e5a 100644 --- a/README.md +++ b/README.md @@ -57,18 +57,28 @@ mcrfpy.setScene("intro") ## Documentation -### 📚 Full Documentation Site +### 📚 Developer Documentation -For comprehensive documentation, tutorials, and API reference, visit: -**[https://mcrogueface.github.io](https://mcrogueface.github.io)** +For comprehensive documentation about systems, architecture, and development workflows: -The documentation site includes: +**[Project Wiki](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki)** -- **[Quickstart Guide](https://mcrogueface.github.io/quickstart)** - Get running in 5 minutes -- **[McRogueFace Does The Entire Roguelike Tutorial](https://mcrogueface.github.io/tutorials)** - Step-by-step game building -- **[Complete API Reference](https://mcrogueface.github.io/api)** - Every function documented -- **[Cookbook](https://mcrogueface.github.io/cookbook)** - Ready-to-use code recipes -- **[C++ Extension Guide](https://mcrogueface.github.io/extending-cpp)** - For C++ developers: Add engine features +Key wiki pages: + +- **[Home](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Home)** - Documentation hub with multiple entry points +- **[Grid System](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Grid-System)** - Three-layer grid architecture +- **[Python Binding System](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Python-Binding-System)** - C++/Python integration +- **[Performance and Profiling](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Performance-and-Profiling)** - Optimization tools +- **[Adding Python Bindings](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Adding-Python-Bindings)** - Step-by-step binding guide +- **[Issue Roadmap](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Issue-Roadmap)** - All 46 open issues organized by system + +### 📖 Development Guides + +In the repository root: + +- **[CLAUDE.md](CLAUDE.md)** - Build instructions, testing guidelines, common tasks +- **[ROADMAP.md](ROADMAP.md)** - Strategic vision and development phases +- **[roguelike_tutorial/](roguelike_tutorial/)** - Complete roguelike tutorial implementations ## Build Requirements @@ -114,7 +124,15 @@ If you are writing a game in Python using McRogueFace, you only need to rename a PRs will be considered! Please include explicit mention that your contribution is your own work and released under the MIT license in the pull request. -The project has a private roadmap and issue list. Reach out via email or social media if you have bugs or feature requests. +### Issue Tracking + +The project uses [Gitea Issues](https://gamedev.ffwf.net/gitea/john/McRogueFace/issues) for task tracking and bug reports. Issues are organized with labels: + +- **System labels** (grid, animation, python-binding, etc.) - identify which codebase area +- **Priority labels** (tier1-active, tier2-foundation, tier3-future) - development timeline +- **Type labels** (Major Feature, Minor Feature, Bugfix, etc.) - effort and scope + +See the [Issue Roadmap](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Issue-Roadmap) on the wiki for organized view of all open tasks. ## License