OpenRoads MUD Release Guide

This guide explains how to create releases for the OpenRoads MUD project using the automated GitLab CI/CD pipeline.

🚀 Release Process Overview

OpenRoads MUD uses an automated release system that:

• ✅ Creates cross-platform binaries automatically

• ✅ Generates GitLab releases with proper assets

• ✅ Validates code quality before release

• ✅ Supports semantic versioning

• ✅ Provides downloadable binaries for all platforms

📦 Supported Platforms

Each release automatically builds binaries for:

Platform	Architecture	Binary Name
Linux	AMD64	openroads-linux-amd64
Windows	AMD64	openroads-windows-amd64.exe
macOS	AMD64	openroads-darwin-amd64
Linux	ARM64	openroads-linux-arm64

🛠️ Creating a Release

Method 1: Using the Release Script (Recommended)

# Run the automated release script
./dev_tools/create-release.sh

The script will guide you through:

1. Version Input: Enter semantic version (e.g., v1.0.0)

2. Release Notes: Add description of changes

3. Validation: Automatically runs all tests

4. Tag Creation: Creates and pushes git tag

5. Pipeline Trigger: Initiates automated build and release

Method 2: Manual Release

# Create a release tag with message
git tag -a v1.0.0 -m "Release version 1.0.0

- Added static NPC system
- Improved enemy spawning
- Enhanced combat mechanics
- Fixed various bugs"

# Push the tag to trigger release pipeline
git push origin v1.0.0

📋 Version Naming Convention

Use Semantic Versioning for all releases:

Release Types

• Major Release: v1.0.0 - Breaking changes or major new features

• Minor Release: v1.1.0 - New features, backward compatible

• Patch Release: v1.0.1 - Bug fixes, backward compatible

Pre-release Versions

• Beta: v1.0.0-beta.1 - Feature complete, testing phase

• Alpha: v1.0.0-alpha.1 - Early development, unstable

• Release Candidate: v1.0.0-rc.1 - Final testing before release

🔄 Release Pipeline Workflow

When a tag is pushed, the following automated process occurs:

Stage 1: Build Cross-platform Binaries

build_binaries:
  - Builds for Linux AMD64, Windows AMD64, macOS AMD64, Linux ARM64
  - Uses optimized build flags for smaller binaries
  - Creates artifacts for release job

Stage 2: Quality Assurance

• All existing CI tests run automatically

• Static NPC system verification

• Enemy spawning system validation

• Combat system testing

• Server stability checks

Stage 3: Release Creation

release_job:
  - Creates GitLab release page
  - Links to all platform binaries
  - Uses tag message as release notes
  - Organizes assets for easy download

📊 Release Checklist

Before creating a release, ensure:

Code Quality

• All tests pass locally (./dev_tools/validate-ci-pipeline.sh)

• Code is properly formatted (gofmt)

• No security vulnerabilities

• Documentation is updated

Functionality

• Static NPCs (Oria, Hanrod, Wenzel) are working

• Enemy spawning system functions correctly

• Combat system is stable

• Server handles multiple connections

• No critical bugs or regressions

Release Preparation

• Version number follows semantic versioning

• Release notes describe changes clearly

• Git working directory is clean

• On main branch (or appropriate release branch)

📝 Writing Release Notes

Good release notes should include:

Structure

## What's New in v1.0.0

### 🎮 New Features
- Added comprehensive static NPC system
- Implemented advanced enemy spawning mechanics
- Enhanced combat system with equipment support

### 🐛 Bug Fixes
- Fixed issue with NPCs not spawning in shops
- Resolved combat timing problems
- Corrected inventory display issues

### ⚡ Improvements
- Optimized server performance
- Enhanced error handling
- Improved logging system

### 🔧 Technical Changes
- Updated Go version to 1.21
- Refactored enemy spawning code
- Added comprehensive test suite

Categories to Include

• New Features: Major additions to functionality

• Bug Fixes: Issues resolved in this release

• Improvements: Enhancements to existing features

• Technical Changes: Internal improvements

• Breaking Changes: Changes that affect compatibility

🎯 Release Examples

Major Release (v1.0.0)

git tag -a v1.0.0 -m "OpenRoads MUD v1.0.0 - First Stable Release

🎮 Major Features:
- Complete static NPC system with shop keepers
- Advanced enemy spawning with tick-based timing
- Full combat system with weapons and armor
- Multi-client server support

🔧 Technical Highlights:
- Comprehensive test suite with 100% CI coverage
- Cross-platform binary support
- Professional development workflow
- Enterprise-grade CI/CD pipeline

This release marks the first stable version of OpenRoads MUD
with all core systems fully implemented and tested."

Minor Release (v1.1.0)

git tag -a v1.1.0 -m "OpenRoads MUD v1.1.0 - Enhanced Gameplay

🎮 New Features:
- Added player statistics tracking
- Implemented advanced look command
- Enhanced inventory management

🐛 Bug Fixes:
- Fixed enemy retaliation timing
- Resolved NPC placement issues
- Corrected combat damage calculations"

Patch Release (v1.0.1)

git tag -a v1.0.1 -m "OpenRoads MUD v1.0.1 - Bug Fixes

🐛 Bug Fixes:
- Fixed critical server crash on startup
- Resolved memory leak in enemy spawning
- Corrected static NPC persistence issue

No new features or breaking changes."

📥 Download and Installation

After release creation, users can download binaries from:

GitLab Releases Page

https://gitlab.com/your-project/-/releases

Direct Binary Links

Each release provides direct download links for:

• Linux: openroads-linux-amd64

• Windows: openroads-windows-amd64.exe

• macOS: openroads-darwin-amd64

• Linux ARM: openroads-linux-arm64

Installation Instructions

# Linux/macOS
chmod +x openroads-linux-amd64
./openroads-linux-amd64

# Windows
# Double-click openroads-windows-amd64.exe
# Or run from command prompt

🔍 Monitoring Releases

GitLab CI Pipeline

Monitor release progress at:

https://gitlab.com/your-project/-/pipelines

Release Status

• ✅ Success: Release created with all binaries

• ⚠️ Partial: Some builds failed, check logs

• ❌ Failed: Release creation failed, fix issues

Troubleshooting

Common issues and solutions:

• Build Failures: Check Go version compatibility

• Test Failures: Ensure all tests pass locally first

• Tag Issues: Verify tag format and permissions

🎉 Post-Release Tasks

After successful release:

1. Announce Release

   • Update project README

   • Notify team/community

   • Update documentation

2. Monitor Feedback

   • Watch for bug reports

   • Monitor server performance

   • Collect user feedback

3. Plan Next Release

   • Review feedback

   • Plan new features

   • Update roadmap

🚀 Conclusion

The OpenRoads MUD release system provides:

• Automated Quality Assurance: Every release is thoroughly tested

• Cross-platform Support: Binaries for all major platforms

• Professional Workflow: Industry-standard release process

• Easy Distribution: Direct download links for users

This ensures that every OpenRoads MUD release is stable, tested, and ready for production use across all supported platforms.