MAID Contribution Guide Video Tutorial Outline¶

This document outlines the structure and content for a video tutorial series on contributing to MAID. The goal is to lower the barrier to entry for new contributors and provide clear, visual guidance on the contribution process.

Series Overview¶

Total Runtime: 45-60 minutes (split into segments) Target Audience: Developers new to MAID who want to contribute Prerequisites: Basic Python knowledge, familiarity with Git

Video 1: Introduction to MAID (8-10 minutes)¶

Section 1.1: What is MAID? (2 min)¶

Script Notes: - Open with the MAID logo and tagline - Explain: "Multi AI Dungeon - A modern MUD engine with AI integration" - Brief history and project goals - Show a quick demo of MAID in action (connect via telnet, walk around, interact)

Key Points: - MAID is open source (MIT license) - Modern Python 3.12+ codebase - Combines classic MUD gameplay with AI capabilities - Active development with welcoming community

Section 1.2: Architecture Overview (3 min)¶

Script Notes: - Show the package architecture diagram from docs - Explain the three-layer structure: - maid-engine: Core infrastructure - maid-stdlib: Common components - maid-classic-rpg: Game content - Emphasize: "You don't need to understand everything to contribute"

Visual Aids: - Package dependency diagram - Code editor showing package structure

Key Points: - Layered architecture keeps concerns separate - Most contributions go to maid-stdlib or maid-classic-rpg - Engine changes require more review but are also welcome

Section 1.3: Ways to Contribute (3 min)¶

Script Notes: - Walk through different contribution types - Show GitHub issues labeled "good first issue" - Explain non-code contributions (docs, testing, reviews)

Key Points: - Code: Bug fixes, features, tests - Documentation: Guides, tutorials, API docs - Plugins: Create and share content packs - Community: Answer questions, review PRs - "Every contribution matters, no matter how small"

Video 2: Setting Up Your Development Environment (10-12 minutes)¶

Section 2.1: Prerequisites (2 min)¶

Script Notes: - List required tools: Python 3.12+, Git, uv - Show how to verify installations - Brief mention of optional tools (Docker, IDE)

Commands to Show:

python --version  # Should be 3.12+
git --version
uv --version

Section 2.2: Forking and Cloning (3 min)¶

Script Notes: - Show GitHub fork button - Clone the forked repository - Add upstream remote for syncing

Commands to Show:

git clone https://github.com/YOUR-USERNAME/MAID.git
cd MAID
git remote add upstream https://github.com/Qworg/MAID.git

Key Points: - Always work from your fork - Keep your fork synced with upstream - Create feature branches for each contribution

Section 2.3: Installing Dependencies (3 min)¶

Script Notes: - Show uv sync command - Explain optional extras (openai, ollama) - Verify installation by running tests

Commands to Show:

uv sync --all-extras
uv run pytest packages/ -v --tb=short

Key Points: - uv handles virtual environment automatically - All dev dependencies included by default - Tests should pass before you start coding

Section 2.4: IDE Setup (3 min)¶

Script Notes: - Show VS Code / PyCharm setup - Configure Python interpreter to use uv venv - Enable type checking and linting

Visual Aids: - IDE settings screenshots - Show ruff and mypy integration

Key Points: - Type hints are required - IDE support helps - Pre-commit hooks catch issues early - Recommended extensions: Python, Ruff, GitLens

Video 3: Making Your First Contribution (15-18 minutes)¶

Section 3.1: Finding an Issue (3 min)¶

Script Notes: - Navigate to GitHub issues - Filter by "good first issue" label - Read issue description and comments - Comment to claim the issue

Visual Aids: - GitHub issues interface - Example good first issue

Key Points: - Check if someone else is already working on it - Ask questions if anything is unclear - Smaller scope = faster review and merge

Section 3.2: Creating a Branch (2 min)¶

Script Notes: - Show branch naming conventions - Create and checkout feature branch

Commands to Show:

# Sync with upstream first
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b fix/issue-123-description

Key Points: - Branch names should be descriptive - Include issue number when applicable - Keep branches focused on single change

Section 3.3: Making Code Changes (5 min)¶

Script Notes: - Walk through a real example: fixing a simple bug - Show the code change - Explain the thought process - Add or update tests

Visual Aids: - Code editor with actual change - Running specific tests

Commands to Show:

# Run tests for specific package
uv run pytest packages/maid-engine/tests/test_specific.py -v

# Run linting
uv run ruff check packages/

# Run type checking
uv run mypy packages/

Key Points: - Write tests for your changes - Follow existing code style - Run linting and type checking locally

Section 3.4: Writing Good Commit Messages (3 min)¶

Script Notes: - Explain conventional commits format - Show examples of good vs bad messages - Demonstrate committing changes

Examples to Show:

# Good
feat(stdlib): add respawn component for entities
fix(engine): handle connection timeout gracefully
docs(readme): add installation instructions

# Bad
fixed stuff
updates
WIP

Key Points: - Use conventional commit format - Describe the "why" not just the "what" - Reference issue numbers where applicable

Section 3.5: Submitting a Pull Request (4 min)¶

Script Notes: - Push branch to fork - Open pull request on GitHub - Fill out PR template - Respond to CI feedback

Commands to Show:

git push -u origin fix/issue-123-description

Visual Aids: - GitHub PR creation interface - PR template being filled out - CI checks running

Key Points: - Write clear PR description - Reference the related issue - Be responsive to review feedback - CI must pass before merge

Video 4: Creating Your First Content Pack (12-15 minutes)¶

Section 4.1: Understanding Content Packs (2 min)¶

Script Notes: - Explain what content packs are - Show examples from maid-classic-rpg - Discuss the ContentPack protocol

Key Points: - Content packs are modular game content - Follow a standard protocol/interface - Can include systems, components, commands, events

Section 4.2: Scaffolding a Content Pack (3 min)¶

Script Notes: - Use the scaffold command - Walk through generated structure - Explain each file's purpose

Commands to Show:

uv run maid scaffold content-pack my-combat-pack \
    --template game-content \
    --with-tests

Visual Aids: - Generated file structure - Each file opened briefly

Section 4.3: Implementing a Simple Feature (5 min)¶

Script Notes: - Add a simple component - Create a system that uses it - Register a command

Code Examples:

# Component
@dataclass
class StaminaComponent(Component):
    current: int = 100
    maximum: int = 100
    regen_rate: float = 1.0

# System
class StaminaRegenSystem(System):
    def update(self, world: World, delta: float) -> None:
        for entity, stamina in world.query(StaminaComponent):
            if stamina.current < stamina.maximum:
                stamina.current = min(
                    stamina.maximum,
                    stamina.current + stamina.regen_rate * delta
                )

Section 4.4: Testing Your Content Pack (3 min)¶

Script Notes: - Write unit tests for component - Write integration test for system - Run tests and show output

Commands to Show:

uv run pytest my-combat-pack/tests/ -v

Section 4.5: Publishing to maid-contrib (2 min)¶

Script Notes: - Overview of submission process - Mention checklist requirements - Submit for review

Key Points: - Follow the plugin checklist - Open a submission PR to maid-contrib - Maintainers will review for quality and security

Video 5: Advanced Contribution Topics (Bonus - 10 min)¶

Section 5.1: Hot Reload Development (3 min)¶

Script Notes: - Enable development mode with hot reload - Show live code changes taking effect - Discuss data migration for schema changes

Section 5.2: RFC Process for Major Changes (3 min)¶

Script Notes: - When to write an RFC - RFC template overview - Review and approval process

Section 5.3: Becoming a Maintainer (2 min)¶

Script Notes: - Path to maintainer status - Responsibilities and privileges - How to express interest

Section 5.4: Community Resources (2 min)¶

Script Notes: - GitHub Discussions - Communication channels - Getting help when stuck

Production Notes¶

Recording Setup¶

Screen Recording: 1920x1080, 30fps
Audio: Clear voiceover, minimal background noise
Code Font: 16px minimum for readability
Terminal Theme: Dark theme with high contrast

Editing Guidelines¶

Add chapter markers for each section
Include captions/subtitles
Highlight key commands and code
Add lower-third graphics for important points
Include links in video description

MAID Contribution Guide Video Tutorial Outline¶

Series Overview¶

Video 1: Introduction to MAID (8-10 minutes)¶

Section 1.1: What is MAID? (2 min)¶

Section 1.2: Architecture Overview (3 min)¶

Section 1.3: Ways to Contribute (3 min)¶

Video 2: Setting Up Your Development Environment (10-12 minutes)¶

Section 2.1: Prerequisites (2 min)¶

Section 2.2: Forking and Cloning (3 min)¶

Section 2.3: Installing Dependencies (3 min)¶

Section 2.4: IDE Setup (3 min)¶

Video 3: Making Your First Contribution (15-18 minutes)¶

Section 3.1: Finding an Issue (3 min)¶

Section 3.2: Creating a Branch (2 min)¶

Section 3.3: Making Code Changes (5 min)¶

Section 3.4: Writing Good Commit Messages (3 min)¶

Section 3.5: Submitting a Pull Request (4 min)¶

Video 4: Creating Your First Content Pack (12-15 minutes)¶

Section 4.1: Understanding Content Packs (2 min)¶

Section 4.2: Scaffolding a Content Pack (3 min)¶

Section 4.3: Implementing a Simple Feature (5 min)¶

Section 4.4: Testing Your Content Pack (3 min)¶

Section 4.5: Publishing to maid-contrib (2 min)¶

Video 5: Advanced Contribution Topics (Bonus - 10 min)¶

Section 5.1: Hot Reload Development (3 min)¶

Section 5.2: RFC Process for Major Changes (3 min)¶

Section 5.3: Becoming a Maintainer (2 min)¶

Section 5.4: Community Resources (2 min)¶

Production Notes¶

Recording Setup¶

Editing Guidelines¶

Distribution¶

Maintenance¶

Additional Resources to Reference¶