Release Process¶

This document describes the release process for MAID packages.

Version Numbering¶

MAID follows Semantic Versioning 2.0.0 (semver):

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └─── Patch: Bug fixes, no API changes
  │     └───────── Minor: New features, backwards compatible
  └─────────────── Major: Breaking changes

Version Examples¶

Change Type	Example	Version Bump
Bug fix	Fix crash in telnet handler	1.2.3 -> 1.2.4
New feature	Add inventory sorting	1.2.3 -> 1.3.0
Breaking change	Change ECS API	1.2.3 -> 2.0.0
Security fix	Patch auth bypass	1.2.3 -> 1.2.4

Pre-release Versions¶

For pre-release versions, we use the following suffixes:

alpha - Early development, unstable: 2.0.0-alpha.1
beta - Feature complete, testing: 2.0.0-beta.1
rc - Release candidate, final testing: 2.0.0-rc.1

Package Versioning¶

All three packages (maid-engine, maid-stdlib, maid-classic-rpg) share the same version number and are released together. This simplifies dependency management.

Release Schedule¶

Regular Releases¶

Patch releases: As needed for bug fixes
Minor releases: Monthly (approximately)
Major releases: When breaking changes are required (announced in advance)

Release Windows¶

We aim to release on the first Monday of each month for minor releases. Patch releases happen as needed.

Release Checklist¶

Pre-Release¶

[ ] All CI checks pass on main
[ ] All tests pass locally
[ ] No critical bugs in issue tracker
[ ] CHANGELOG.md updated with all changes
[ ] Documentation updated for new features
[ ] Migration guide written (if breaking changes)
[ ] Announce planned release in Discussions (1 week notice for minor+)

Prepare Release¶

Create release branch

git checkout main
git pull origin main
git checkout -b release/v3.2.0

Update version numbers

Update pyproject.toml in all packages:

# packages/maid-engine/pyproject.toml
# packages/maid-stdlib/pyproject.toml
# packages/maid-classic-rpg/pyproject.toml

Update CHANGELOG.md

Move "Unreleased" section to new version:

## [3.2.0] - 2024-02-01

### Added
- New feature X (#123)

### Changed
- Improved Y (#124)

### Fixed
- Bug in Z (#125)

Create pull request

git add -A
git commit -m "Release v3.2.0"
git push origin release/v3.2.0
# Create PR targeting main

Review and merge
Requires approval from at least one core maintainer
All CI checks must pass

Tag and Publish¶

Create git tag

git checkout main
git pull origin main
git tag -a v3.2.0 -m "Release v3.2.0"
git push origin v3.2.0

Build packages

cd packages/maid-engine && uv build
cd packages/maid-stdlib && uv build
cd packages/maid-classic-rpg && uv build

Publish to PyPI

# Test PyPI first (optional)
uv publish --repository testpypi

# Production PyPI
uv publish

Create GitHub Release
Go to Releases > Create new release
Select the tag
Title: v3.2.0
Body: Copy from CHANGELOG.md
Attach built wheels if desired
Mark as "Latest release"

Post-Release¶

[ ] Verify packages on PyPI
[ ] Test installation: pip install maid-engine==3.2.0
[ ] Announce release:
GitHub Discussions
Discord (planned)
Social media
[ ] Update documentation site
[ ] Close milestone on GitHub

Hotfix Process¶

For critical bugs or security issues that need immediate release:

1. Create Hotfix Branch¶

# Branch from the release tag
git checkout v3.2.0
git checkout -b hotfix/v3.2.1

2. Apply Fix¶

Make minimal, targeted changes
Add tests for the fix
Update CHANGELOG.md

3. Fast-Track Review¶

Requires only one reviewer for critical fixes
Security fixes may skip public PR (use private advisory)

4. Release¶

git commit -m "Fix: Critical bug in auth system (#999)"
git tag -a v3.2.1 -m "Hotfix v3.2.1"
git push origin hotfix/v3.2.1 --tags

5. Merge Back to Main¶

git checkout main
git merge hotfix/v3.2.1
git push origin main

Rollback Procedure¶

If a release has critical issues:

Yank from PyPI (if security issue)

# Mark version as yanked (doesn't delete, but warns users)
# Done through PyPI web interface

Communicate immediately
Post in GitHub Discussions
Update GitHub Release notes
Notify known affected users
Release hotfix following hotfix process above
Post-mortem
Document what went wrong
Update release checklist if needed
Share learnings with team

Changelog Guidelines¶

We follow Keep a Changelog format:

Categories¶

Added - New features
Changed - Changes to existing functionality
Deprecated - Features to be removed in future
Removed - Features removed in this release
Fixed - Bug fixes
Security - Security fixes

Good Changelog Entry¶

### Fixed
- Fix crash when player inventory exceeds 100 items (#456) - @contributor

Bad Changelog Entry¶

### Fixed
- Fixed bug

Contributor Credit¶

Always credit contributors: - (#123) - Link to issue/PR - @username - GitHub username

Automation¶

CI/CD Pipeline¶

Our GitHub Actions workflow handles:

Running tests on all PRs
Building packages on tagged releases
Publishing to PyPI (with maintainer approval)
Updating documentation site

Future Enhancement: CI Benchmark Enforcement

Performance benchmarks exist in packages/maid-engine/tests/benchmarks/ but are not currently enforced in CI. This is tracked as technical debt. Planned enhancements include:

Automated benchmark runs with regression detection

Configurable performance thresholds for CI gates

Historical performance tracking across releases

See the Performance Guide for benchmark details and manual execution instructions.

Release Automation (Planned)¶

Automated version bumping
Changelog generation from commit messages
Draft release notes from PR titles

Questions?¶

Contact a core maintainer or ask in GitHub Discussions.

See also: MAINTAINERS.md for who can perform releases.