Migration Guide Template¶

This document serves as a template for creating migration guides when releasing new versions of MAID with breaking changes.

Migration Guide: vX.Y to vX.Z¶

Breaking Changes

This upgrade contains breaking changes. Please read this guide carefully before upgrading.

Overview¶

Provide a brief summary of:

Why this version exists (major features, architectural changes)
Estimated migration effort (small/medium/large)
Key breaking changes at a glance

Prerequisites¶

Before migrating, ensure you have:

[ ] Read this entire guide
[ ] Backed up your data
[ ] Tested the upgrade in a non-production environment
[ ] Reviewed your content packs for compatibility

Breaking Changes¶

1. Change Category Name¶

What changed: Describe the change in detail.

Why it changed: Explain the reasoning behind the change.

Migration steps:

# Before (vX.Y)
old_code_example()

# After (vX.Z)
new_code_example()

Automated migration: If available, describe any automated migration tools.

# Run the migration script
uv run maid migrate --from vX.Y --to vX.Z

2. Another Breaking Change¶

What changed: ...

Why it changed: ...

Migration steps: ...

Deprecated Features¶

Deprecation Notice

The following features are deprecated and will be removed in version vX.Z+1.

Feature	Deprecated In	Removed In	Replacement
`old_function()`	vX.Z	vX.Z+1	`new_function()`
`OldClass`	vX.Z	vX.Z+1	`NewClass`

old_function()¶

The old_function() has been deprecated in favor of new_function().

# Deprecated (will be removed in vX.Z+1)
from maid_engine import old_function
old_function()

# Recommended
from maid_engine import new_function
new_function()

New Features¶

Feature 1: Name¶

Brief description of the new feature.

Usage:

from maid_engine import new_feature

# Example usage
result = new_feature.do_something()

Documentation: Link to full documentation

Feature 2: Another Feature¶

...

Configuration Changes¶

New Configuration Options¶

# New environment variables
MAID_NEW_OPTION=value
MAID_ANOTHER_OPTION=value

Changed Configuration Options¶

Old Option	New Option	Notes
`MAID_OLD`	`MAID_NEW`	Renamed for clarity
`MAID_REMOVED`	N/A	No longer needed

Database Migrations¶

If this version includes database schema changes:

# Backup your database first!
uv run maid db backup

# Run migrations
uv run maid db migrate

# Verify migration
uv run maid db status

Content Pack Compatibility¶

Required Updates¶

Content packs must update the following:

Manifest version: Update api_version to "X.Z"
Protocol changes: Implement new ContentPack protocol methods

# pack.py
class MyContentPack:
    @property
    def manifest(self) -> ContentPackManifest:
        return ContentPackManifest(
            name="my-pack",
            version="1.0.0",
            api_version="X.Z",  # Updated
            # ...
        )

    # New required method in vX.Z
    async def on_migrate(self, from_version: str) -> None:
        """Handle data migration from previous versions."""
        pass

Testing Your Migration¶

Run the test suite:
```
uv run pytest packages/
```
Test your content packs:
```
uv run pytest your-content-pack/tests/
```

Run the compatibility checker:

uv run maid content check-compatibility my-pack

Rollback Procedure¶

If you need to rollback:

Stop the server
Restore your database backup
Reinstall the previous version:
```
uv add maid-engine==X.Y.0
```
Restart the server

Common Issues¶

Issue: "ModuleNotFoundError: No module named 'old_module'"¶

Solution: The module has been renamed. Update your imports:

# Old
from maid_engine.old_module import Thing

# New
from maid_engine.new_module import Thing

Issue: "TypeError: unexpected keyword argument 'old_param'"¶

Solution: The parameter has been renamed or removed. Check the API documentation.

Getting Help¶

Discord: Join our Discord
GitHub Issues: Report issues
Discussions: Ask questions

Changelog¶

For a complete list of changes, see the Changelog.

Template Checklist¶

When writing a migration guide, ensure you cover:

[ ] All breaking changes with clear before/after examples
[ ] Deprecation warnings with timeline
[ ] New features (briefly, with links to full docs)
[ ] Configuration changes
[ ] Database migration steps (if applicable)
[ ] Content pack compatibility requirements
[ ] Testing instructions
[ ] Rollback procedure
[ ] Common issues and solutions
[ ] Links to support channels