Contributing to MAID¶

Welcome! We're excited that you're interested in contributing to MAID. This guide will help you get started.

Quick Links¶

Document	Description
Development Setup	Setting up your development environment
Style Guide	Code style requirements
Testing Guide	Writing and running tests
RFC Process	How to propose significant changes
Release Process	How we release new versions
Exception Handling	Exception handling policy and best practices
maid-contrib	Official plugin repository
Plugin Review Process	Plugin review criteria and workflow
Plugin Checklist	Pre-submission checklist for plugins
MAINTAINERS.md	Project maintainers and governance
SECURITY.md	Security policy and reporting
AUTHORS.md	Contributor recognition

Ways to Contribute¶

Code Contributions¶

Bug fixes: Check issues labeled bug and good first issue
Features: Look for issues labeled enhancement or help wanted
Documentation: Help improve guides, tutorials, and API docs
Tests: Increase test coverage, add edge cases

Plugin Contributions¶

Create and share your own content packs with the MAID community:

Create a plugin: Build your own content packs using the Publishing Guide
Submit to maid-contrib: Share your plugin with the community via the official plugin repository
Review plugins: Help review community plugin submissions

See the Plugin Submission Checklist to prepare your plugin for submission.

Non-Code Contributions¶

Bug reports: Found a bug? Open an issue
Feature requests: Have an idea? Start a Discussion
Code review: Review open pull requests
Community help: Answer questions in Discussions
Documentation review: Proofread and suggest improvements

Getting Started¶

1. Fork and Clone¶

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR-USERNAME/MAID.git
cd MAID

2. Set Up Development Environment¶

# Install dependencies
uv sync --all-extras

# Run tests to verify setup
uv run pytest packages/

3. Create a Branch¶

# Create a feature branch
git checkout -b feature/my-awesome-feature

# Or for bug fixes
git checkout -b fix/issue-123-description

4. Make Your Changes¶

Follow the existing code style
Add tests for new functionality
Update documentation as needed

5. Test Your Changes¶

# Run all tests
uv run pytest packages/

# Run linting
uv run ruff check packages/

# Run type checking
uv run mypy packages/

6. Submit a Pull Request¶

Push your branch to your fork
Open a PR against main
Fill out the PR template
Wait for review

Code Style¶

Python¶

Follow PEP 8
Use type hints everywhere
Maximum line length: 88 characters (black default)
Use ruff for linting
Use mypy for type checking (strict mode)

Commit Messages¶

We follow Conventional Commits:

type(scope): description

[optional body]

[optional footer]

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes (formatting, etc.) - refactor: Code refactoring - test: Adding or updating tests - chore: Maintenance tasks

Examples:

feat(engine): add hot reload for content packs
fix(telnet): handle connection timeout gracefully
docs(readme): add installation instructions

Pull Requests¶

Keep PRs focused and reasonably sized
Reference related issues: Fixes #123
Update CHANGELOG.md for user-facing changes
Respond to review feedback promptly

Development Guidelines¶

Package Architecture¶

MAID is a monorepo with three packages:

packages/
├── maid-engine/      # Core infrastructure (no game logic)
├── maid-stdlib/      # Common components and utilities
└── maid-classic-rpg/ # Game content

Keep these boundaries: - maid-engine must not import from other packages - maid-stdlib may only import from maid-engine - maid-classic-rpg may import from both

Testing¶

Write tests for all new code
Place tests in the tests/ directory of each package
Use pytest fixtures for common setup
Aim for > 80% coverage on new code

Documentation¶

Use Google-style docstrings
Update user documentation for new features
Include code examples in docstrings

Community¶

Communication Channels¶

GitHub Issues: Bug reports and feature requests
GitHub Discussions: Questions, ideas, and general discussion
Discord: Real-time chat (planned)

Code of Conduct¶

We are committed to providing a welcoming and inclusive experience for everyone. Please read our Code of Conduct before participating.

Getting Help¶

Stuck on setup? Open a Discussion
Unclear documentation? File an issue
Need guidance on a contribution? Ask in your PR or Discussion

Recognition¶

All contributors are recognized in AUTHORS.md. Make sure to add yourself when your first PR is merged!

License¶

By contributing to MAID, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to MAID! Every contribution, no matter how small, helps make the project better.