Skip to content

maid-contrib: Official Plugin Repository

The maid-contrib repository is the official collection of community-contributed plugins for MAID. It provides a curated, quality-assured collection of content packs that extend MAID's functionality.

Overview

What is maid-contrib?

maid-contrib serves as:

  1. Official Plugin Repository - A centralized location for community plugins that meet MAID's quality standards
  2. Quality Assurance - All plugins undergo review to ensure they follow best practices
  3. Compatibility Guarantee - Plugins are tested against supported MAID versions
  4. Discovery Hub - Easy browsing and installation of vetted plugins

Repository Structure

maid-contrib/
    plugins/
        maid-space-adventure/       # Individual plugin packages
        maid-western-frontier/
        maid-magic-schools/
        ...
    shared/
        testing/                     # Shared testing utilities
        ci/                          # Shared CI configurations
    docs/
        CONTRIBUTING.md
        REVIEW_PROCESS.md
    pyproject.toml                   # Workspace configuration

Submitting a Plugin

Eligibility Requirements

To submit a plugin to maid-contrib, your plugin must:

  1. Follow the ContentPack Protocol - Implement all required protocol methods
  2. Have Comprehensive Tests - Minimum 80% code coverage
  3. Include Documentation - README with installation, usage, and API docs
  4. Use Appropriate Licensing - Open source license (MIT, Apache 2.0, GPL, BSD, etc.)
  5. Pass Quality Checks - Linting, type checking, and security review

Submission Process

Step 1: Prepare Your Plugin

Ensure your plugin meets all requirements by running the quality checker:

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

Review the Plugin Submission Checklist to verify all requirements are met.

Step 2: Submit via GitHub Issue

  1. Go to the MAID repository
  2. Create a new issue using the Plugin Submission template
  3. Fill out all required fields:
  4. Plugin name and description
  5. Repository URL
  6. Category
  7. Compatible MAID version
  8. Installation instructions
  9. Basic usage example

Step 3: Review Process

After submission:

  1. Initial Triage (1-2 days) - Maintainers review the submission for completeness
  2. Technical Review (3-5 days) - Code review for quality, security, and compatibility
  3. Community Feedback (optional) - Open for community comments
  4. Final Decision - Approval, request for changes, or rejection with explanation

See Plugin Review Process for detailed review criteria.

Step 4: Integration

Once approved:

  1. Your plugin is added to maid-contrib
  2. CI/CD pipelines are configured
  3. Documentation is published
  4. Plugin appears in the registry

Plugin Categories

Plugins in maid-contrib are organized by category:

Category Description Examples
World/Environment Rooms, areas, world generation Procedural dungeons, biomes
Combat/Battle System Combat mechanics, damage systems Tactical combat, turn-based battles
Magic/Spells Magic systems, spell effects Schools of magic, ritual casting
Crafting/Economy Crafting, trading, currency Smithing, alchemy, marketplaces
NPCs/AI NPC behavior, dialogue systems Quest givers, merchants, enemies
Quests/Storylines Quest frameworks, story content Quest chains, branching narratives
Social/Multiplayer Guilds, chat, social features Clans, parties, voice chat
UI/Client Client enhancements, displays Status bars, maps, color themes
Integration External services, APIs Discord bots, web dashboards
Utility/Tools Developer tools, debugging Logging, profiling, admin tools
Complete Game Full game settings Sci-fi MUD, fantasy realm

Quality Standards

All maid-contrib plugins must adhere to:

Code Quality

  • Type hints on all public APIs
  • Docstrings for modules, classes, and functions (Google style)
  • Linting passes with ruff (MAID's default configuration)
  • No security vulnerabilities in dependencies

Testing

  • Unit tests for all components, systems, and commands
  • Integration tests for plugin loading and interaction
  • Minimum 80% code coverage
  • Protocol compliance tests pass

Documentation

  • README.md with:
  • Clear description of functionality
  • Installation instructions
  • Quick start guide
  • Command reference
  • Configuration options
  • CHANGELOG.md documenting all changes
  • LICENSE file with OSI-approved license

Compatibility

  • Declares minimum MAID version compatibility
  • Tested against all supported MAID versions
  • Documents any breaking changes between versions

Maintaining Your Plugin

After your plugin is accepted:

Responsibilities

  1. Respond to Issues - Address bug reports and questions
  2. Update for Compatibility - Keep plugin compatible with new MAID versions
  3. Follow Security Practices - Update dependencies, fix vulnerabilities
  4. Maintain Documentation - Keep docs current with changes

Version Updates

To release a new version:

  1. Update version in pyproject.toml and manifest
  2. Update CHANGELOG.md
  3. Create a pull request to maid-contrib
  4. Version is released after passing CI

Deprecation and Removal

Plugins may be deprecated or removed if:

  • Maintainer is unresponsive for extended periods (>6 months)
  • Critical security issues are not addressed
  • Plugin becomes incompatible and cannot be updated
  • Maintainer requests removal

Before removal, the community will be notified and given opportunity to adopt the plugin.

Benefits of maid-contrib

For Plugin Authors

  • Visibility - Your plugin is discoverable through official channels
  • Quality Badge - "maid-contrib verified" status
  • CI/CD - Automated testing and releases
  • Community - Support from MAID maintainers and community
  • Feedback - Code review improves your code

For Users

  • Trust - Plugins are reviewed for quality and security
  • Compatibility - Guaranteed to work with supported MAID versions
  • Support - Active maintenance and community support
  • Easy Installation - Simple maid plugin install command

Getting Help

  • Questions about submission? Open a GitHub Discussion
  • Technical issues? File a bug report
  • Review status? Check your submission issue for updates
  • General help? Join our Discord community