mirror of
https://github.com/azerothcore/mod-ale
synced 2025-11-29 15:38:17 +08:00
Chore: Update Docs .md files (#343)
This commit is contained in:
iThorgrim
407
docs/MERGING.md
Normal file
407
docs/MERGING.md
Normal file
@@ -0,0 +1,407 @@
|
||||
<div align="center">
|
||||
|
||||
# 🔀 Advanced ALE Integration
|
||||
|
||||
*Customizing and extending ALE for your specific needs*
|
||||
|
||||
[](https://discord.com/invite/ZKSVREE7)
|
||||
[](http://www.azerothcore.org/)
|
||||
|
||||
---
|
||||
</div>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> ALE is distributed as an AzerothCore module. Unlike traditional forks, you don't need to merge code. However, this guide covers advanced integration scenarios for custom AzerothCore builds.
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
- [Standard Installation](#-standard-installation)
|
||||
- [Custom AzerothCore Builds](#-custom-azerothcore-builds)
|
||||
- [Maintaining Custom Changes](#-maintaining-custom-changes)
|
||||
- [Updating ALE](#-updating-ale)
|
||||
- [Contributing Back](#-contributing-back)
|
||||
- [Troubleshooting](#-troubleshooting)
|
||||
|
||||
## ✅ Standard Installation
|
||||
|
||||
For most users, installing ALE is straightforward:
|
||||
|
||||
```bash
|
||||
# Navigate to modules directory
|
||||
cd <azerothcore-path>/modules
|
||||
|
||||
# Clone ALE
|
||||
git clone https://github.com/azerothcore/mod-ale.git
|
||||
|
||||
# Rebuild AzerothCore
|
||||
cd <azerothcore-build-directory>
|
||||
cmake ../ -DLUA_VERSION=luajit
|
||||
make -j$(nproc)
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> If you're using the standard AzerothCore setup, see the [Installation Guide](INSTALL.md) instead. This guide is for advanced scenarios only.
|
||||
|
||||
## 🔧 Custom AzerothCore Builds
|
||||
|
||||
### Working with Forked AzerothCore
|
||||
|
||||
If you maintain a fork of AzerothCore with custom modifications:
|
||||
|
||||
#### Step 1: Add ALE as a Submodule (Recommended)
|
||||
|
||||
```bash
|
||||
cd <your-azerothcore-fork>
|
||||
|
||||
# Add ALE as a submodule
|
||||
git submodule add https://github.com/azerothcore/mod-ale.git modules/mod-ale
|
||||
|
||||
# Initialize and update
|
||||
git submodule init
|
||||
git submodule update
|
||||
|
||||
# Commit the submodule addition
|
||||
git add .gitmodules modules/mod-ale
|
||||
git commit -m "Add mod-ale as submodule"
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Easy updates with `git submodule update`
|
||||
- Tracks specific ALE versions
|
||||
- Clean separation between your code and ALE
|
||||
|
||||
#### Step 2: Configure Build
|
||||
|
||||
Your CMake configuration should automatically detect the module:
|
||||
|
||||
```bash
|
||||
cd build
|
||||
cmake ../ -DLUA_VERSION=luajit
|
||||
make -j$(nproc)
|
||||
```
|
||||
|
||||
### Alternative: Clone Directly
|
||||
|
||||
If you prefer not to use submodules:
|
||||
|
||||
```bash
|
||||
cd <your-azerothcore-fork>/modules
|
||||
git clone https://github.com/azerothcore/mod-ale.git
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> **Not Recommended:** Avoid adding the `modules/mod-ale` directory to your fork's git repository. It makes updates more difficult.
|
||||
|
||||
Add to your `.gitignore`:
|
||||
```
|
||||
modules/mod-ale/
|
||||
```
|
||||
|
||||
## 🛠️ Maintaining Custom Changes
|
||||
|
||||
### Modifying ALE for Your Server
|
||||
|
||||
If you need to customize ALE:
|
||||
|
||||
#### Option 1: Fork ALE (Recommended)
|
||||
|
||||
1. **Fork the repository** on GitHub
|
||||
2. **Clone your fork** instead of the official repository:
|
||||
```bash
|
||||
cd modules
|
||||
git clone https://github.com/YOUR_USERNAME/mod-ale.git
|
||||
```
|
||||
3. **Make your changes** in a feature branch
|
||||
4. **Keep in sync** with upstream:
|
||||
```bash
|
||||
git remote add upstream https://github.com/azerothcore/mod-ale.git
|
||||
git fetch upstream
|
||||
git merge upstream/master
|
||||
```
|
||||
|
||||
#### Option 2: Patch Files
|
||||
|
||||
For small changes, create patch files:
|
||||
|
||||
```bash
|
||||
# Make your changes to ALE
|
||||
cd modules/mod-ale
|
||||
|
||||
# Create a patch
|
||||
git diff > ../../patches/ale-custom-changes.patch
|
||||
|
||||
# Apply the patch after updating
|
||||
git pull
|
||||
git apply ../../patches/ale-custom-changes.patch
|
||||
```
|
||||
|
||||
### Recommended Approach: Extension Scripts
|
||||
|
||||
Instead of modifying ALE core, create extension scripts:
|
||||
|
||||
**File:** `lua_scripts/extensions/custom_functions.lua`
|
||||
```lua
|
||||
-- Extend existing classes with custom methods
|
||||
function Player:CustomMethod()
|
||||
-- Your custom functionality
|
||||
end
|
||||
|
||||
function Creature:CustomBehavior()
|
||||
-- Your custom functionality
|
||||
end
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- No ALE core modifications needed
|
||||
- Easy to update ALE
|
||||
- Clean separation of custom code
|
||||
- Portable across ALE versions
|
||||
|
||||
## 🔄 Updating ALE
|
||||
|
||||
### Standard Update Process
|
||||
|
||||
For standard installations:
|
||||
|
||||
```bash
|
||||
cd modules/mod-ale
|
||||
git pull
|
||||
cd ../../build
|
||||
make -j$(nproc)
|
||||
```
|
||||
|
||||
### Updating with Submodules
|
||||
|
||||
If you added ALE as a submodule:
|
||||
|
||||
```bash
|
||||
# Update to latest ALE
|
||||
git submodule update --remote modules/mod-ale
|
||||
|
||||
# Or update all submodules
|
||||
git submodule update --remote
|
||||
|
||||
# Commit the update
|
||||
git add modules/mod-ale
|
||||
git commit -m "Update mod-ale to latest version"
|
||||
```
|
||||
|
||||
### Updating with Custom Changes
|
||||
|
||||
If you maintain a fork:
|
||||
|
||||
```bash
|
||||
cd modules/mod-ale
|
||||
|
||||
# Fetch upstream changes
|
||||
git fetch upstream
|
||||
|
||||
# Merge or rebase your changes
|
||||
git merge upstream/master
|
||||
# or
|
||||
git rebase upstream/master
|
||||
|
||||
# Resolve any conflicts
|
||||
# Then rebuild
|
||||
cd ../../build
|
||||
make -j$(nproc)
|
||||
```
|
||||
|
||||
### Version Pinning
|
||||
|
||||
To pin a specific ALE version:
|
||||
|
||||
```bash
|
||||
cd modules/mod-ale
|
||||
|
||||
# List available tags
|
||||
git tag
|
||||
|
||||
# Checkout specific version
|
||||
git checkout v1.2.3
|
||||
|
||||
# Or specific commit
|
||||
git checkout abc123def
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> Pin versions in production environments for stability. Use latest in development for new features.
|
||||
|
||||
## 🤝 Contributing Back
|
||||
|
||||
If you've made improvements that could benefit others:
|
||||
|
||||
### Preparing a Contribution
|
||||
|
||||
1. **Ensure it's generic**: Your change should be useful for the broader community
|
||||
2. **Follow coding standards**: See [Contributing Guide](CONTRIBUTING.md)
|
||||
3. **Test thoroughly**: Verify your changes don't break existing functionality
|
||||
4. **Document changes**: Add comments and update documentation
|
||||
|
||||
### Submission Process
|
||||
|
||||
1. **Fork the official repository**
|
||||
2. **Create a feature branch**:
|
||||
```bash
|
||||
git checkout -b feature/my-improvement
|
||||
```
|
||||
3. **Make your changes**
|
||||
4. **Push to your fork**:
|
||||
```bash
|
||||
git push origin feature/my-improvement
|
||||
```
|
||||
5. **Open a Pull Request** on GitHub
|
||||
|
||||
See the [Contributing Guide](CONTRIBUTING.md) for detailed instructions.
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Merge Conflicts
|
||||
|
||||
If you encounter conflicts when updating:
|
||||
|
||||
```bash
|
||||
# Check which files have conflicts
|
||||
git status
|
||||
|
||||
# Edit conflicting files to resolve
|
||||
# Look for conflict markers: <<<<<<<, =======, >>>>>>>
|
||||
|
||||
# Mark as resolved
|
||||
git add <resolved-file>
|
||||
|
||||
# Complete the merge
|
||||
git merge --continue
|
||||
```
|
||||
|
||||
### Module Not Loading
|
||||
|
||||
**Check CMake configuration:**
|
||||
```bash
|
||||
cd build
|
||||
cmake ../ -DLUA_VERSION=luajit
|
||||
```
|
||||
|
||||
Look for output like:
|
||||
```
|
||||
-- ALE module found: /path/to/modules/mod-ale
|
||||
```
|
||||
|
||||
**Verify module directory structure:**
|
||||
```
|
||||
modules/
|
||||
└── mod-ale/
|
||||
├── CMakeLists.txt
|
||||
├── src/
|
||||
│ └── LuaEngine/
|
||||
└── conf/
|
||||
```
|
||||
|
||||
### Build Errors After Update
|
||||
|
||||
**Clean build recommended:**
|
||||
```bash
|
||||
cd build
|
||||
rm -rf *
|
||||
cmake ../ -DLUA_VERSION=luajit
|
||||
make -j$(nproc)
|
||||
```
|
||||
|
||||
### Submodule Issues
|
||||
|
||||
**Submodule not initialized:**
|
||||
```bash
|
||||
git submodule init
|
||||
git submodule update
|
||||
```
|
||||
|
||||
**Submodule in detached HEAD state:**
|
||||
```bash
|
||||
cd modules/mod-ale
|
||||
git checkout master
|
||||
git pull
|
||||
```
|
||||
|
||||
## 🎯 Advanced Scenarios
|
||||
|
||||
### Multiple ALE Versions
|
||||
|
||||
Testing with different ALE versions:
|
||||
|
||||
```bash
|
||||
# Clone to different directories
|
||||
cd modules
|
||||
git clone https://github.com/azerothcore/mod-ale.git mod-ale-stable
|
||||
git clone https://github.com/azerothcore/mod-ale.git mod-ale-dev
|
||||
|
||||
# Switch between them
|
||||
ln -sf mod-ale-stable mod-ale # Use stable
|
||||
ln -sf mod-ale-dev mod-ale # Use dev
|
||||
```
|
||||
|
||||
### Custom Lua Version
|
||||
|
||||
Using a custom Lua installation:
|
||||
|
||||
```bash
|
||||
cmake ../ \
|
||||
-DLUA_VERSION=custom \
|
||||
-DLUA_INCLUDE_DIR=/path/to/lua/include \
|
||||
-DLUA_LIBRARIES=/path/to/lua/lib/liblua.a
|
||||
```
|
||||
|
||||
### Automated Updates
|
||||
|
||||
Create an update script:
|
||||
|
||||
**File:** `scripts/update-ale.sh`
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
cd modules/mod-ale || exit 1
|
||||
|
||||
echo "Fetching latest ALE..."
|
||||
git fetch upstream
|
||||
|
||||
echo "Current version: $(git rev-parse --short HEAD)"
|
||||
echo "Latest version: $(git rev-parse --short upstream/master)"
|
||||
|
||||
read -p "Update to latest? (y/n) " -n 1 -r
|
||||
echo
|
||||
if [[ $REPLY =~ ^[Yy]$ ]]; then
|
||||
git merge upstream/master
|
||||
cd ../../build
|
||||
make -j$(nproc)
|
||||
echo "ALE updated successfully!"
|
||||
fi
|
||||
```
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
- **[Installation Guide](INSTALL.md)** - Standard installation process
|
||||
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute changes
|
||||
- **[Usage Guide](USAGE.md)** - Getting started with scripting
|
||||
- **[AzerothCore Documentation](http://www.azerothcore.org/)** - Core documentation
|
||||
|
||||
### Getting Help
|
||||
|
||||
- **GitHub Issues**: [Report problems](https://github.com/azerothcore/mod-ale/issues)
|
||||
- **Discord**: [Join our community](https://discord.com/invite/bx3y5Qmy)
|
||||
- **AzerothCore Discord**: [Get support](http://www.azerothcore.org/)
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Acknowledgements
|
||||
|
||||
ALE is built upon the foundation of the [Eluna Lua Engine](https://github.com/ElunaLuaEngine/Eluna). We acknowledge and thank the Eluna team for their pioneering work in Lua scripting for World of Warcraft server emulators.
|
||||
|
||||
- **[Original Eluna Repository](https://github.com/ElunaLuaEngine/Eluna)**
|
||||
- **[Eluna Discord Community](https://discord.gg/bjkCVWqqfX)**
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>Developed with ❤️ by the AzerothCore and ALE community</sub>
|
||||
|
||||
[⬆ Back to Top](#-advanced-ale-integration)
|
||||
</div>
|
||||
Reference in New Issue
Block a user