Skip to content

Plugin Submission Checklist

Use this checklist to prepare your plugin for submission to maid-contrib. Complete all required items before submitting your plugin.

Quick Check

Run the automated quality checker to verify most requirements:

uv run maid plugin check /path/to/your/plugin

This will check protocol compliance, tests, coverage, linting, type hints, and documentation.

Pre-Submission Checklist

Required Files

Your plugin repository must contain these files:

  • [ ] pyproject.toml - Package configuration with correct metadata
  • [ ] README.md - Comprehensive documentation
  • [ ] LICENSE - OSI-approved open source license
  • [ ] CHANGELOG.md - Version history
  • [ ] src/<package>/__init__.py - Package entry point with exports
  • [ ] src/<package>/pack.py - ContentPack implementation
  • [ ] src/<package>/py.typed - Type hint marker file
  • [ ] tests/ - Test directory with test files
  • [ ] tests/conftest.py - Pytest fixtures

pyproject.toml Requirements

Verify your pyproject.toml includes:

[project]
name = "maid-your-plugin-name"        # Must start with "maid-"
version = "x.y.z"                      # Semantic version
description = "Clear description"      # One-line description
readme = "README.md"
license = {text = "MIT"}               # Or other OSI-approved license
requires-python = ">=3.12"
authors = [
    {name = "Your Name", email = "you@example.com"},
]
keywords = ["maid", "mud", ...]        # Include "maid"
classifiers = [
    "Development Status :: ...",
    "Programming Language :: Python :: 3.12",
    "Topic :: Games/Entertainment :: Multi-User Dungeons (MUD)",
]

dependencies = [
    "maid-engine>=0.2.0",              # Declare MAID dependency
]

[project.entry-points."maid.content_packs"]
your-plugin = "your_plugin:YourContentPack"  # Entry point for discovery

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
  • [ ] Name starts with maid-
  • [ ] Version follows semantic versioning
  • [ ] Description is clear and concise
  • [ ] License is specified
  • [ ] Python 3.12+ required
  • [ ] Authors with valid email
  • [ ] Keywords include "maid"
  • [ ] MUD classifier present
  • [ ] MAID dependencies declared
  • [ ] Entry point configured
  • [ ] Build system specified

README.md Requirements

Your README must include these sections:

  • [ ] Title and Badge - Plugin name with relevant badges
  • [ ] Description - What the plugin does (2-3 sentences)
  • [ ] Features - Bulleted list of features
  • [ ] Installation - How to install (uv add or pip install)
  • [ ] Quick Start - Minimal working example with code
  • [ ] Commands - Table of all commands with usage
  • [ ] Events - Table of events emitted/handled (if any)
  • [ ] Components - Table of components provided (if any)
  • [ ] Configuration - Environment variables and settings
  • [ ] Requirements - MAID version and other dependencies
  • [ ] License - License type

Example README structure:

# Your Plugin Name

Brief description of what your plugin does.

## Features

- Feature 1
- Feature 2

## Installation

\`\`\`bash
uv add maid-your-plugin
\`\`\`

## Quick Start

\`\`\`python
from maid_engine import GameEngine
from your_plugin import YourContentPack

engine = GameEngine(settings)
engine.load_content_pack(YourContentPack())
await engine.start()
\`\`\`

## Commands

| Command | Description | Usage |
|---------|-------------|-------|
| `cmd1`  | Does thing  | `cmd1 <arg>` |

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `MAID_YOUR_PLUGIN__SETTING` | `value` | What it does |

## Requirements

- MAID Engine >= 0.2.0
- Python >= 3.12

## License

MIT License

Testing Requirements

  • [ ] Tests exist - tests/ directory with test files
  • [ ] Tests pass - All tests pass with uv run pytest
  • [ ] Coverage >= 80% - Minimum 80% line coverage
  • [ ] Protocol tests - Tests verify ContentPack protocol compliance
  • [ ] Component tests - Unit tests for all components
  • [ ] System tests - Unit tests for all systems
  • [ ] Command tests - Unit tests for all command handlers
  • [ ] Integration tests - Tests for plugin loading and interactions

Verify coverage:

uv run pytest tests/ --cov=your_plugin --cov-report=term-missing

Code Quality Requirements

  • [ ] Linting passes - uv run ruff check src/
  • [ ] Formatting passes - uv run ruff format --check src/
  • [ ] Type checking passes - uv run mypy src/
  • [ ] No TODO comments - Resolve or document all TODOs
  • [ ] No commented code - Remove unused commented code
  • [ ] Consistent style - Follow PEP 8 conventions

Documentation Requirements

  • [ ] All public classes documented - Google-style docstrings
  • [ ] All public functions documented - Args, Returns, Raises sections
  • [ ] Module docstrings - Each module has a top-level docstring
  • [ ] Type hints complete - All public APIs have type hints
  • [ ] Examples in docstrings - Complex functions include examples

Example docstring:

def process_command(player: Entity, args: list[str]) -> str:
    """Process the custom command for a player.

    Executes the command logic and returns the result message
    to be displayed to the player.

    Args:
        player: The entity executing the command.
        args: Command arguments provided by the player.

    Returns:
        The message to display to the player.

    Raises:
        CommandError: If the command cannot be executed.

    Example:
        >>> result = process_command(player, ["arg1", "arg2"])
        >>> print(result)
        "Command executed successfully!"
    """

Security Requirements

  • [ ] No hardcoded secrets - No API keys, passwords, or tokens in code
  • [ ] Input validation - All user input is validated
  • [ ] No unsafe operations - No eval(), exec(), or pickle.loads() with untrusted data
  • [ ] Safe file operations - Path traversal prevention
  • [ ] Dependency audit - No known vulnerabilities in dependencies

Check for vulnerabilities:

uv run pip-audit

Protocol Compliance

Your ContentPack must implement:

  • [ ] manifest property - Returns valid ContentPackManifest
  • [ ] get_dependencies() - Returns list of dependency pack names
  • [ ] get_systems() - Returns list of System instances
  • [ ] get_events() - Returns list of Event types
  • [ ] register_commands() - Registers commands with registry
  • [ ] register_document_schemas() - Registers persistence schemas
  • [ ] on_load() async - Handles pack loading
  • [ ] on_unload() async - Handles pack unloading

Example implementation:

from maid_engine.plugins.protocol import ContentPack, ContentPackManifest

class YourContentPack(ContentPack):
    @property
    def manifest(self) -> ContentPackManifest:
        return ContentPackManifest(
            name="your-plugin",
            version="1.0.0",
            description="Plugin description",
            author="Your Name",
        )

    def get_dependencies(self) -> list[str]:
        return ["maid-stdlib"]

    def get_systems(self, world: World) -> list[System]:
        return [YourSystem(world)]

    def get_events(self) -> list[type[Event]]:
        return [YourEvent]

    def register_commands(self, registry: CommandRegistry) -> None:
        registry.register("yourcommand", your_command_handler)

    def register_document_schemas(self, store: DocumentStore) -> None:
        store.register_collection("your_data", YourDataSchema)

    async def on_load(self, engine: GameEngine) -> None:
        pass  # Initialization logic

    async def on_unload(self, engine: GameEngine) -> None:
        pass  # Cleanup logic

Submission Form Preparation

Before filling out the submission form, prepare these items:

Required Information

  • [ ] Plugin Name - Name of your plugin (without maid- prefix)
  • [ ] Repository URL - Public GitHub/GitLab URL
  • [ ] PyPI Name - Package name if published to PyPI (optional)
  • [ ] Description - 2-3 sentence description of functionality
  • [ ] Category - Select the most appropriate category
  • [ ] Compatible MAID Version - Minimum version (e.g., >=0.2.0)
  • [ ] Dependencies - List of MAID plugin dependencies
  • [ ] Installation Instructions - Command to install
  • [ ] Usage Example - Code showing how to use the plugin
  • [ ] License - License type

Optional Information

  • [ ] Documentation URL - Link to full documentation
  • [ ] Demo/Screenshots - Visual examples
  • [ ] Video Tutorial - Link to demo video

Final Verification

Run these final checks before submitting:

# Run all quality checks
uv run maid plugin check /path/to/plugin

# Verify the package builds
uv build

# Verify the package installs
uv pip install dist/maid_your_plugin-*.whl

# Verify entry point works
python -c "from your_plugin import YourContentPack; print(YourContentPack().manifest)"

Submission Confirmation

Before submitting, confirm the following:

  • [ ] I have read and understand the Plugin Review Process
  • [ ] I have read and understand the maid-contrib guidelines
  • [ ] All items in this checklist are complete
  • [ ] I am the author or have permission to submit this plugin
  • [ ] I agree to maintain this plugin and respond to issues
  • [ ] I agree to the contribution license agreement

After Submission

  1. Monitor your submission issue for feedback
  2. Respond promptly to reviewer questions
  3. Make requested changes in a timely manner
  4. Celebrate when your plugin is approved!

Getting Help

If you have questions while preparing your submission: