Skip to content

MAID Documentation & Community Design Specification

Document Version: 1.0
Date: January 30, 2026
Status: Draft
Authors: MAID Development Team

Executive Summary

This document specifies enhancements to MAID's documentation and community infrastructure to achieve feature parity with Evennia's mature documentation ecosystem. The four major enhancement areas are:

  1. Getting Started Tutorial - Multi-part tutorial for new developers
  2. API Reference Documentation - Auto-generated, searchable API docs
  3. Tutorial Game World - Example game demonstrating all features
  4. Community Infrastructure - Discord, forums, contribution guidelines

These enhancements address the critical gaps identified in the MAID vs Evennia comparison where Evennia leads significantly in documentation quality, tutorial content, and community presence.

Table of Contents

  1. Feature 1: Getting Started Tutorial
  2. Feature 2: API Reference Documentation
  3. Feature 3: Tutorial Game World
  4. Feature 4: Community Infrastructure
  5. Appendix A: Documentation Standards
  6. Appendix B: Content Maintenance Plan

Feature 1: Getting Started Tutorial

1.1 Feature Overview

What it does:
Provides a comprehensive, step-by-step tutorial series that takes developers from zero knowledge to building their first complete MAID game. The tutorial covers installation, core concepts, and building progressively complex features.

Why it's needed: - Current state: Only CLAUDE.md with architecture overview and README with basic install - No guided learning path for new developers - Evennia provides a 5-part beginner tutorial with working examples - New developers abandon projects they can't quickly understand

1.2 Tutorial Structure

The Getting Started Tutorial consists of 7 interconnected parts:

Part Title Duration Prerequisites
1 Installation & First Run 30 min Python knowledge
2 Architecture Deep Dive 45 min Part 1
3 Your First Commands 45 min Part 2
4 Creating Rooms & Items 60 min Part 3
5 NPCs & Basic AI 60 min Part 4
6 Combat & Skills 90 min Part 5
7 Your First Content Pack 90 min Part 6

1.3 Part 1: Installation & First Run

1.3.1 Content Outline

# Part 1: Installation & First Run

## What You'll Learn
- Installing MAID using uv
- Starting your first server
- Connecting as a player
- Understanding the project structure

## Prerequisites
- Python 3.12+
- Basic Python knowledge
- Terminal/command line familiarity

## Step 1: Install uv (if needed)
[Instructions for macOS, Linux, Windows]

## Step 2: Create Your Project
```bash
mkdir my-mud && cd my-mud
uv init
uv add maid-engine maid-stdlib maid-classic-rpg
```

## Step 3: Start the Server
```bash
uv run maid server start
```
*Screenshot of successful startup*

## Step 4: Connect to Your Game
*Instructions for telnet and web client*
*Screenshot of login screen*

## Step 5: Create Your First Character
[Walkthrough of character creation]

## Step 6: Explore the Project Structure
[Explanation of directory layout]

## What's Next?
In Part 2, we'll dive deep into MAID's architecture...

## Exercises
1. Start the server with debug mode enabled
2. Connect using both telnet and web client
3. Try the built-in commands (help, look, who)

1.3.2 Key Learning Objectives

  • Successfully install MAID from PyPI
  • Start a server with default settings
  • Connect using telnet and web client
  • Navigate the basic project structure
  • Verify installation is working

1.4 Part 2: Architecture Deep Dive

1.4.1 Content Outline

# Part 2: Architecture Deep Dive

## What You'll Learn
- The Entity-Component-System (ECS) pattern
- How the tick loop works
- The event system
- Content pack architecture

## The ECS Pattern

### Entities
Entities are just UUIDs with attached components.
[Code example showing entity creation]

### Components
Components hold data, not behavior.
[Code example showing component definition]

### Systems
Systems contain the logic that processes components.
[Code example showing system implementation]

[Diagram: Entity -> Components <- Systems]

## The Game Loop

MAID runs on a tick-based loop (default 4 TPS):
[Diagram of tick loop]

```python
# Simplified tick loop
async def tick(delta: float):
    # 1. Process pending events
    await event_bus.process_pending()

    # 2. Run all systems in priority order
    for system in sorted(systems, key=lambda s: s.priority):
        await system.update(world, delta)

    # 3. Commit any world changes
    world.commit()
```

## The Event System

Events are the nervous system of MAID:
[Code example of event subscription and emission]

## Content Packs

MAID uses a layered content pack system:
[Diagram showing maid-engine -> maid-stdlib -> maid-classic-rpg]

## Key Files to Know

| File | Purpose |
|------|---------|
| `engine.py` | Main game engine |
| `world.py` | World state management |
| `events.py` | Event bus implementation |
| `registry.py` | Command registration |

## What's Next?
In Part 3, we'll create our first custom commands...

1.5 Part 3: Your First Commands

1.5.1 Content Outline

# Part 3: Your First Commands

## What You'll Learn
- Command handler structure
- Registering commands
- Argument parsing
- Sending output to players

## Your First Command

Let's create a simple "greet" command:

```python
# my_commands.py
from maid_engine.commands.registry import CommandContext

async def cmd_greet(ctx: CommandContext) -> bool:
    """Greet someone in the room."""
    if not ctx.args:
        await ctx.session.send_line("Greet who?")
        return False

    target = ctx.args[0]
    await ctx.session.send_line(f"You wave at {target}.")

    # Notify everyone else in the room
    room_id = ctx.world.room_index.get_room(ctx.player_id)
    for entity_id in ctx.world.entities_in_room(room_id):
        if entity_id != ctx.player_id:
            session = ctx.world.get_session(entity_id)
            if session:
                player_name = ctx.world.get_name(ctx.player_id)
                await session.send_line(f"{player_name} waves at {target}.")

    return True
```

## Registering Your Command

```python
# In your content pack's register_commands():
registry.register(
    name="greet",
    handler=cmd_greet,
    aliases=["wave"],
    category="social",
    description="Greet someone in the room",
    usage="greet <person>",
)
```

## Using Typed Arguments

MAID provides a decorator-based argument system:

```python
from maid_engine.commands.decorators import arguments
from maid_engine.commands.arguments import ArgumentSpec, ArgumentType

@arguments(
    ArgumentSpec("target", ArgumentType.ENTITY, description="Who to greet"),
)
async def cmd_greet(ctx: CommandContext, args: ParsedArguments) -> bool:
    target = args["target"].entity
    await ctx.session.send_line(f"You wave at {target.name}.")
    return True
```

## Exercise: Create These Commands
1. A "time" command that shows in-game time
2. A "roll" command that rolls dice (e.g., "roll 2d6")
3. A "whisper" command for private messages

1.6 Parts 4-7 (Abbreviated Outlines)

Part 4: Creating Rooms & Items

  • Room entity structure
  • Creating rooms programmatically
  • Builder commands
  • Item templates and spawning
  • Exercise: Build a 5-room dungeon

Part 5: NPCs & Basic AI

  • NPC entity structure
  • Behavior components
  • Dialogue systems
  • Patrol and wander behaviors
  • Exercise: Create a shopkeeper NPC

Part 6: Combat & Skills

  • Combat system overview
  • Damage and healing
  • Skill checks and progression
  • Creating new abilities
  • Exercise: Add a custom combat skill

Part 7: Your First Content Pack

  • Content pack protocol
  • Package structure
  • Dependency declaration
  • Publishing to PyPI
  • Exercise: Package and publish your dungeon

1.7 Acceptance Criteria

ID Criterion Verification
AC-1.1 All 7 tutorial parts are complete and published Manual review
AC-1.2 Each part takes estimated time ±20% User testing
AC-1.3 Code examples are tested and working Automated testing
AC-1.4 Screenshots are current with latest version Manual review
AC-1.5 Exercises have solution files available File existence
AC-1.6 New developer can complete tutorial solo User testing
AC-1.7 Tutorial is linked from main README Link verification

Feature 2: API Reference Documentation

2.1 Feature Overview

What it does:
Provides comprehensive, auto-generated API documentation for all public MAID APIs. Documentation is searchable, cross-referenced, and includes examples for key classes.

Why it's needed: - Current state: Only inline docstrings, no generated docs - Developers can't discover APIs without reading source - Evennia provides full auto-generated API reference - Search functionality is essential for large APIs

2.2 Technical Approach

2.2.1 Documentation Generator

We will use Sphinx with the following extensions: - sphinx-autodoc - Auto-generate from docstrings - sphinx-autodoc-typehints - Include type annotations - sphinx-copybutton - Copy code button - sphinx-design - Tabs, cards, grids - myst-parser - Markdown support - furo - Modern theme

2.2.2 Project Structure

docs/
├── conf.py                     # Sphinx configuration
├── index.md                    # Documentation home
├── getting-started/
│   ├── installation.md
│   ├── quickstart.md
│   └── tutorial/
│       ├── part1.md
│       ├── part2.md
│       └── ...
├── concepts/
│   ├── architecture.md
│   ├── ecs.md
│   ├── events.md
│   ├── commands.md
│   └── content-packs.md
├── guides/
│   ├── building-worlds.md
│   ├── creating-npcs.md
│   ├── combat-systems.md
│   └── ai-integration.md
├── api/
│   ├── maid-engine/
│   │   ├── core/
│   │   ├── commands/
│   │   ├── config/
│   │   └── ...
│   ├── maid-stdlib/
│   └── maid-classic-rpg/
├── contributing/
│   ├── development.md
│   ├── style-guide.md
│   └── testing.md
└── changelog.md

2.2.3 Sphinx Configuration

# docs/conf.py

project = "MAID"
copyright = "2026, MAID Development Team"
author = "MAID Development Team"

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autodoc.typehints",
    "sphinx.ext.intersphinx",
    "sphinx.ext.viewcode",
    "sphinx.ext.napoleon",
    "sphinx_copybutton",
    "sphinx_design",
    "myst_parser",
]

# Theme
html_theme = "furo"
html_theme_options = {
    "light_css_variables": {
        "color-brand-primary": "#2b6cb0",
        "color-brand-content": "#2b6cb0",
    },
    "dark_css_variables": {
        "color-brand-primary": "#63b3ed",
        "color-brand-content": "#63b3ed",
    },
}

# Autodoc settings
autodoc_default_options = {
    "members": True,
    "undoc-members": True,
    "show-inheritance": True,
    "member-order": "bysource",
}

autodoc_typehints = "description"
autodoc_typehints_format = "short"

# Napoleon settings for Google-style docstrings
napoleon_google_docstring = True
napoleon_numpy_docstring = False
napoleon_include_init_with_doc = True

# Intersphinx
intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "asyncio": ("https://docs.python.org/3/library/asyncio", None),
}

# MyST settings
myst_enable_extensions = [
    "colon_fence",
    "deflist",
    "tasklist",
]

2.3 Documentation Standards

2.3.1 Docstring Format

All public APIs must use Google-style docstrings:

def create_entity(
    self,
    components: list[Component] | None = None,
    tags: set[str] | None = None,
) -> Entity:
    """Create a new entity in the world.

    Creates an entity with a unique UUID and optionally attaches
    components and tags. The entity is immediately registered in
    the world's entity registry.

    Args:
        components: Optional list of components to attach.
        tags: Optional set of string tags for filtering.

    Returns:
        The newly created Entity.

    Raises:
        WorldError: If the world is not running.

    Example:
        >>> entity = world.create_entity(
        ...     components=[PositionComponent(x=0, y=0)],
        ...     tags={"player", "human"},
        ... )
        >>> print(entity.id)
        UUID('...')

    Note:
        Entities created during a tick are immediately available
        but won't be processed by systems until the next tick.

    See Also:
        - :meth:`destroy_entity`: Remove an entity
        - :class:`Entity`: The entity class
    """

2.3.2 Class Documentation

class EventBus:
    """Central event dispatch system for MAID.

    The EventBus implements a publish-subscribe pattern for decoupled
    communication between game systems. Events are dispatched asynchronously
    and handlers are called in priority order.

    Attributes:
        pending_count: Number of events waiting to be processed.

    Example:
        >>> bus = EventBus()
        >>> 
        >>> @bus.subscribe(PlayerLoginEvent, priority=Priority.HIGH)
        ... async def on_login(event: PlayerLoginEvent):
        ...     print(f"Player {event.player_name} logged in!")
        ...
        >>> await bus.emit(PlayerLoginEvent(player_name="Alice"))
        Player Alice logged in!

    Note:
        Handlers are called in priority order (HIGHEST first).
        If a handler raises an exception, subsequent handlers
        are still called.

    See Also:
        - :class:`Event`: Base event class
        - :class:`Priority`: Handler priority levels
    """

2.4 Build and Deploy

2.4.1 Local Build

# Install docs dependencies
uv add --group docs sphinx furo myst-parser sphinx-autodoc-typehints sphinx-copybutton sphinx-design

# Build docs
cd docs
make html

# Preview locally
python -m http.server -d _build/html 8000

2.4.2 CI/CD Pipeline

# .github/workflows/docs.yml

name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Install dependencies
        run: uv sync --group docs

      - name: Build documentation
        run: |
          cd docs
          uv run make html

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html

2.5 Search Functionality

Sphinx provides built-in search via sphinx.ext.search. For enhanced search:

  1. Local Search: Use sphinx-search extension for client-side search
  2. Hosted Search: Use Algolia DocSearch for larger sites
# docs/conf.py additions for Algolia

extensions.append("sphinx_search.extension")

html_context = {
    "algolia_app_id": "YOUR_APP_ID",
    "algolia_api_key": "YOUR_API_KEY",
    "algolia_index_name": "maid-docs",
}

2.6 Acceptance Criteria

ID Criterion Verification
AC-2.1 All public APIs have docstrings CI check (interrogate)
AC-2.2 Docs build without warnings CI check
AC-2.3 Search returns relevant results Manual testing
AC-2.4 Examples in docs are tested doctest
AC-2.5 Cross-references work Link checker
AC-2.6 Docs deploy on push to main CI verification
AC-2.7 Docs are mobile-friendly Manual testing
AC-2.8 API docs include all 3 packages File existence

Feature 3: Tutorial Game World

3.1 Feature Overview

What it does:
Provides a complete, playable example game that demonstrates all MAID features. The tutorial world serves as both a learning resource and reference implementation.

Why it's needed: - Current state: No example game to learn from - New developers need working examples to understand patterns - Evennia provides EvAdventure as a complete tutorial game - Reference implementations prevent common mistakes

3.2 Tutorial World Design

3.2.1 Game Concept

"The Maid's Quest" - A small but complete adventure game:

  • Setting: A fantasy village threatened by goblins
  • Size: 25-30 rooms across 4 areas
  • Features: All core MAID systems demonstrated
  • Playtime: 1-2 hours to complete

3.2.2 Area Layout

THE VILLAGE (8 rooms)
├── Village Square (start)
├── General Store
├── Blacksmith
├── Inn (with NPC dialogue)
├── Temple (healing)
├── Guard Post
├── Village Well
└── Village Gate (exit to forest)

THE DARK FOREST (10 rooms)
├── Forest Entrance
├── Winding Path (3 rooms)
├── Clearing (random encounters)
├── Ancient Tree (landmark)
├── Goblin Tracks (skill check)
└── Goblin Camp Entrance

GOBLIN CAMP (6 rooms)
├── Camp Perimeter
├── Guard Post (combat)
├── Prisoner Tent (rescue quest)
├── Treasure Tent (loot)
├── Chief's Hut (boss)
└── Escape Tunnel

HIDDEN CAVE (4 rooms)
├── Cave Entrance (hidden)
├── Crystal Chamber
├── Underground Pool
└── Ancient Shrine (magic system demo)

3.3 Feature Demonstrations

Each area demonstrates specific MAID features:

Area Features Demonstrated
Village NPC dialogue, shops, healing, quests
Forest Random encounters, skill checks, exploration
Goblin Camp Combat, stealth, puzzles, boss fight
Hidden Cave Magic system, crafting, secrets

3.4 Implementation Structure

packages/maid-tutorial-world/
├── src/maid_tutorial_world/
│   ├── __init__.py
│   ├── pack.py              # ContentPack implementation
│   ├── areas/
│   │   ├── village.py       # Village rooms and NPCs
│   │   ├── forest.py        # Forest rooms and encounters
│   │   ├── goblin_camp.py   # Combat area
│   │   └── hidden_cave.py   # Magic area
│   ├── npcs/
│   │   ├── shopkeeper.py    # Trading demo
│   │   ├── quest_giver.py   # Quest system demo
│   │   ├── goblin.py        # Enemy AI
│   │   └── boss.py          # Boss encounter
│   ├── items/
│   │   ├── weapons.py
│   │   ├── potions.py
│   │   └── quest_items.py
│   ├── quests/
│   │   ├── rescue_prisoner.py
│   │   └── defeat_chief.py
│   ├── commands/
│   │   └── tutorial_commands.py  # Tutorial-specific commands
│   ├── systems/
│   │   └── progress_tracker.py
│   └── data/
│       ├── rooms.yaml       # Room definitions
│       ├── npcs.yaml        # NPC definitions
│       └── items.yaml       # Item definitions
├── tests/
│   ├── test_village.py
│   └── test_combat.py
└── pyproject.toml

3.5 Code Annotations

Tutorial world code is heavily commented to explain patterns:

# packages/maid-tutorial-world/src/maid_tutorial_world/npcs/shopkeeper.py

"""Shopkeeper NPC demonstrating trading and dialogue.

This module shows how to:
1. Create an NPC with dialogue options
2. Implement a simple trading system
3. Persist NPC state (inventory, gold)
4. React to player actions via events

The shopkeeper restocks daily and remembers regular customers.
"""

from maid_engine.core.ecs.entity import Entity
from maid_engine.core.events import EventBus
from maid_stdlib.components import (
    NPCComponent,
    DialogueComponent,
    InventoryComponent,
    GoldComponent,
)
from maid_classic_rpg.events import ItemPurchasedEvent


async def create_shopkeeper(world: World) -> Entity:
    """Create the village shopkeeper NPC.

    TUTORIAL NOTE: NPCs are created as entities with specialized
    components. The ShopkeeperComponent handles trading logic,
    while DialogueComponent manages conversation trees.

    This shopkeeper demonstrates:
    - Component composition for NPC behavior
    - Event-driven reactions (restocking)
    - Persistent state (remembers purchases)
    """
    shopkeeper = world.create_entity(
        tags={"npc", "shopkeeper", "friendly"},
    )

    # TUTORIAL: Each component adds specific capabilities
    shopkeeper.add_component(NPCComponent(
        name="Old Tom",
        short_desc="a grizzled old shopkeeper",
        long_desc="Old Tom has run this shop for forty years...",
    ))

    # TUTORIAL: Dialogue trees define conversation options
    shopkeeper.add_component(DialogueComponent(
        greeting="Welcome to my shop! Browse my wares?",
        topics={
            "wares": "I sell weapons, armor, and potions.",
            "rumors": "I heard goblins are stirring in the forest...",
            "village": "Been quiet here since the hero left.",
        },
    ))

    # TUTORIAL: Inventory holds items for sale
    shopkeeper.add_component(InventoryComponent(
        capacity=100,
        items=[
            create_sword(),    # From items.py
            create_potion(),
            create_armor(),
        ],
    ))

    return shopkeeper

3.6 Hint System

A built-in hint system helps players who get stuck:

# packages/maid-stdlib/src/maid_stdlib/systems/hint_system.py

class HintSystem(System):
    """Provides contextual hints to stuck players.

    TUTORIAL NOTE: This system demonstrates:
    - Tracking player progress
    - Contextual help based on location and state
    - Non-intrusive guidance
    """

    HINTS = {
        "stuck_at_gate": (
            "The guard won't let you pass without a weapon. "
            "Have you visited the blacksmith?"
        ),
        "lost_in_forest": (
            "You seem lost. Try using the 'track' command to follow "
            "the goblin trails, or 'recall' to return to the village."
        ),
        "boss_too_hard": (
            "The goblin chief is tough! Make sure you have healing "
            "potions and consider finding better gear first."
        ),
    }

    async def update(self, world: World, delta: float) -> None:
        """Check for stuck players and offer hints."""
        for player_id in self._get_active_players(world):
            if self._player_seems_stuck(player_id, world):
                hint = self._get_contextual_hint(player_id, world)
                if hint:
                    session = world.get_session(player_id)
                    await session.send_line(f"\n[HINT] {hint}\n")

3.7 Acceptance Criteria

ID Criterion Verification
AC-3.1 Tutorial world installs as separate package pip install test
AC-3.2 All 25+ rooms are accessible Automated walkthrough
AC-3.3 All MAID features are demonstrated Feature checklist
AC-3.4 Game is completable in under 2 hours Playtest
AC-3.5 Code comments explain all patterns Code review
AC-3.6 Hint system works for common stuck points Playtest
AC-3.7 Tests cover all major game paths Coverage report
AC-3.8 Game works with default MAID install Integration test

Feature 4: Community Infrastructure

4.1 Feature Overview

What it does:
Establishes community channels, contribution guidelines, and processes for building an active MAID community.

Why it's needed: - Current state: No community presence - Open source projects need community for sustainability - Evennia has 15+ years of active community - Community drives adoption, bug reports, and contributions

4.2 Discord Server

4.2.1 Channel Structure

MAID Discord Server
├── INFORMATION
│   ├── #welcome           - Server rules, links
│   ├── #announcements     - Version releases, news
│   └── #showcase          - Community game showcases
├── HELP
│   ├── #general-help      - General questions
│   ├── #installation      - Install issues
│   └── #code-help         - Code questions
├── DEVELOPMENT
│   ├── #dev-discussion    - Feature discussions
│   ├── #pull-requests     - PR announcements
│   └── #testing           - Testing coordination
├── COMMUNITY
│   ├── #general           - Off-topic chat
│   ├── #game-dev          - MUD development discussion
│   └── #introductions     - New member intros
└── VOICE
    └── #dev-chat          - Voice discussions

4.2.2 Discord Bot Integration

Create a bot that bridges game and Discord:

# Bot features:
# - Link Discord account to game character
# - Receive game notifications in Discord
# - Basic game queries (!status, !who, !help)
# - GitHub integration for PR notifications

4.3 GitHub Discussions

Enable GitHub Discussions for:

Category Purpose
Announcements Official announcements
Q&A Question and answer
Ideas Feature suggestions
Show and Tell Community projects
General General discussion

4.4 Contribution Guidelines

4.4.1 CONTRIBUTING.md

# Contributing to MAID

Thank you for your interest in contributing to MAID! This document
provides guidelines for contributing to the project.

## Ways to Contribute

1. **Report Bugs** - File issues for bugs you find
2. **Suggest Features** - Open discussions for feature ideas
3. **Improve Docs** - Fix typos, add examples, write guides
4. **Write Code** - Fix bugs, implement features
5. **Review PRs** - Review pull requests from others
6. **Help Others** - Answer questions in Discord/GitHub

## Getting Started

### Setting Up Development Environment

```bash
git clone https://github.com/your-org/maid.git
cd maid
uv sync --all-extras
uv run pytest  # Verify tests pass
```

### Running Tests

```bash
# All tests
uv run pytest

# Specific package
uv run pytest packages/maid-engine/tests/

# With coverage
uv run pytest --cov=packages
```

### Code Style

We use:
- `ruff` for linting
- `mypy` for type checking
- `black` (via ruff) for formatting

Run before committing:
```bash
uv run ruff check --fix .
uv run mypy packages/
```

## Pull Request Process

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run tests and linting
6. Commit with descriptive message
7. Push to your fork
8. Open a Pull Request

### PR Requirements

- [ ] Tests pass
- [ ] New code has tests
- [ ] Docstrings for public APIs
- [ ] Type hints for all functions
- [ ] No linting errors
- [ ] CHANGELOG updated (if applicable)

## Commit Messages

Use conventional commits:
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation only
- `style:` Formatting, no code change
- `refactor:` Code change, no functionality change
- `test:` Adding tests
- `chore:` Maintenance tasks

Example: `feat(commands): add argument parsing decorators`

## Code of Conduct

Please read our [Code of Conduct](https://github.com/Qworg/MAID/blob/main/CODE_OF_CONDUCT.md) before
contributing.

## Questions?

- Discord: [Join our server](https://discord.gg/...)
- Discussions: [GitHub Discussions](https://github.com/.../discussions)

4.4.2 Code of Conduct

Adopt the Contributor Covenant Code of Conduct:

# Contributor Covenant Code of Conduct

## Our Pledge

We as members, contributors, and leaders pledge to make participation
in our community a harassment-free experience for everyone...

[Full Contributor Covenant text]

4.5 Issue Templates

4.5.1 Bug Report Template

# .github/ISSUE_TEMPLATE/bug_report.yml

name: Bug Report
description: Report a bug in MAID
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for reporting a bug! Please fill out this template.

  - type: textarea
    id: description
    attributes:
      label: Description
      description: A clear description of the bug
    validations:
      required: true

  - type: textarea
    id: reproduction
    attributes:
      label: Steps to Reproduce
      description: Steps to reproduce the behavior
      placeholder: |
        1. Run command '...'
        2. Connect to server
        3. See error
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: Expected Behavior
      description: What you expected to happen
    validations:
      required: true

  - type: textarea
    id: logs
    attributes:
      label: Error Logs
      description: Paste any relevant error messages
      render: shell

  - type: input
    id: version
    attributes:
      label: MAID Version
      description: Output of `maid --version`
    validations:
      required: true

  - type: input
    id: python
    attributes:
      label: Python Version
      description: Output of `python --version`
    validations:
      required: true

4.5.2 Feature Request Template

# .github/ISSUE_TEMPLATE/feature_request.yml

name: Feature Request
description: Suggest a new feature
labels: ["enhancement", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for suggesting a feature! Please describe your idea.

  - type: textarea
    id: problem
    attributes:
      label: Problem Statement
      description: What problem does this solve?
    validations:
      required: true

  - type: textarea
    id: solution
    attributes:
      label: Proposed Solution
      description: How would you like this to work?
    validations:
      required: true

  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives Considered
      description: Other solutions you've thought about

  - type: dropdown
    id: package
    attributes:
      label: Affected Package
      options:
        - maid-engine
        - maid-stdlib
        - maid-classic-rpg
        - Documentation
        - Other

4.6 Release Process

4.6.1 Versioning

Follow Semantic Versioning (SemVer): - MAJOR: Breaking changes - MINOR: New features, backward compatible - PATCH: Bug fixes, backward compatible

4.6.2 Release Checklist

## Release Checklist

### Pre-Release
- [ ] All tests pass on main
- [ ] CHANGELOG.md updated
- [ ] Version bumped in pyproject.toml
- [ ] Documentation updated
- [ ] Breaking changes documented

### Release
- [ ] Create release branch (`release/vX.Y.Z`)
- [ ] Create GitHub release with notes
- [ ] Publish to PyPI (`uv publish`)
- [ ] Announce in Discord #announcements
- [ ] Tweet/social media announcement

### Post-Release
- [ ] Verify PyPI packages work
- [ ] Update documentation site
- [ ] Close milestone on GitHub
- [ ] Create next milestone

4.7 Acceptance Criteria

ID Criterion Verification
AC-4.1 Discord server is set up with channels Manual verification
AC-4.2 GitHub Discussions enabled Setting check
AC-4.3 CONTRIBUTING.md is complete Manual review
AC-4.4 Code of Conduct adopted File existence
AC-4.5 Issue templates created File existence
AC-4.6 PR template created File existence
AC-4.7 Release process documented Manual review
AC-4.8 First 10 community members joined Discord count

Appendix A: Documentation Standards

Writing Style

  1. Use Active Voice: "The system creates..." not "The entity is created by..."
  2. Be Concise: Remove unnecessary words
  3. Use Examples: Every concept needs a code example
  4. Define Jargon: Explain MUD-specific terms
  5. Version Notes: Mark new features with version added

Docstring Requirements

Every public API must have: - One-line summary - Extended description (if complex) - Args section with types - Returns section - Raises section (if applicable) - Example section (for key APIs)

Screenshots/Diagrams

  • Save as PNG, max 1000px wide
  • Use dark theme for terminal screenshots
  • Create diagrams with Mermaid or draw.io
  • Include alt text for accessibility

Appendix B: Content Maintenance Plan

Quarterly Tasks

  • [ ] Review tutorial for accuracy with latest version
  • [ ] Update screenshots if UI changed
  • [ ] Check all external links
  • [ ] Review community metrics
  • [ ] Update roadmap

On Each Release

  • [ ] Update API docs
  • [ ] Add release notes
  • [ ] Update version references
  • [ ] Test tutorial with new version
  • [ ] Announce to community

Community Health Metrics

Track monthly: - Discord member count - GitHub stars - Open issues/PRs - Response time to issues - New contributors

Document History

Version Date Author Changes
1.0 2026-01-30 MAID Team Initial specification