mod-ale/docs/CONTRIBUTING.md

🤝 Contributing to ALE

Help improve the AzerothCore Lua Engine

---

Important

We welcome contributions from everyone! Whether you code or not, there are many ways to help improve ALE.

📋 Table of Contents

• Ways to Contribute
• Contributing Code
• Reporting Issues
• Improving Documentation
• Creating Scripts
• Development Guidelines

🌟 Ways to Contribute

You don't need to be a developer to contribute to ALE! Here are various ways you can help:

💻 For Developers

• Fix Bugs: Browse open issues and submit fixes
• Add Features: Implement new functionality
• Improve Performance: Optimize existing code
• Write Tests: Help ensure code quality
• Review Pull Requests: Provide feedback on proposed changes

📚 For Writers

• Improve Documentation: Fix typos, clarify explanations, add examples
• Write Tutorials: Create guides for common use cases
• Translate: Help make documentation available in other languages
• API Documentation: Document undocumented functions

🎮 For Scripters

• Create Example Scripts: Share useful script templates
• Report Script Issues: Help identify API problems
• Share Best Practices: Document scripting patterns
• Test New Features: Verify new functionality works as expected

💬 For Community Members

• Answer Questions: Help others on Discord or GitHub
• Report Bugs: Submit detailed issue reports
• Test Releases: Try pre-release versions and provide feedback
• Spread the Word: Share ALE with other server administrators

💻 Contributing Code

Getting Started

1. Set up Git if you haven't already

2. Fork the repository to your GitHub account:

   • Main repository: mod-ale
   • Core engine: ALE source in mod-ale

3. Clone your fork to your local machine:

   git clone https://github.com/YOUR_USERNAME/mod-ale.git
   cd mod-ale
   

4. Add the upstream repository:

   git remote add upstream https://github.com/azerothcore/mod-ale.git
   

Development Workflow

1. Create a feature branch from master:

   git checkout master
   git pull upstream master
   git checkout -b feature/my-awesome-feature
   

2. Make your changes:

   • Write clean, readable code
   • Follow existing code style
   • Add comments where necessary
   • Test your changes thoroughly

3. Commit your changes:

   git add .
   git commit -m "Add feature: description of what you did"
   

   Commit Message Guidelines:

   • Use clear, descriptive messages
   • Start with a verb (Add, Fix, Update, Remove, etc.)
   • Keep the first line under 50 characters
   • Add detailed explanation in subsequent lines if needed

   Add new Player:GetQuestStatus method
   
   This method allows scripts to check the status of a player's quest
   without needing to retrieve the full quest object. This improves
   performance for common quest-checking scenarios.
   

4. Push to your fork:

   git push origin feature/my-awesome-feature
   

5. Open a Pull Request:

   • Go to your fork on GitHub
   • Click "New Pull Request"
   • Select your feature branch
   • Provide a clear description of your changes
   • Link any related issues

Code Style Guidelines

C++ Code

// Use clear, descriptive names
int GetPlayerLevel(Player* player)
{
    if (!player)
        return 0;

    return player->getLevel();
}

// Prefer modern C++ features
std::vector<uint32> GetPlayerQuests(Player* player)
{
    std::vector<uint32> quests;
    // ... implementation
    return quests;
}

Key Points:

• Use 4 spaces for indentation (no tabs)
• Opening braces on the same line for functions
• Use meaningful variable names
• Add comments for complex logic
• Follow existing patterns in the codebase

Lua Code (for examples/tests)

-- Use local variables
local QUEST_STATUS_COMPLETE = 1

-- Clear, descriptive function names
local function OnQuestComplete(event, player, quest)
    if not player or not quest then
        return
    end

    local questId = quest:GetId()
    print("Player", player:GetName(), "completed quest", questId)
end

-- Register with clear event IDs
RegisterPlayerEvent(8, OnQuestComplete)  -- PLAYER_EVENT_ON_QUEST_COMPLETE

Testing Your Changes

Before submitting a PR:

1. Compile the code without errors
2. Test basic functionality with your changes
3. Test edge cases (nil values, invalid input, etc.)
4. Verify no regressions (existing features still work)
5. Test on a real server if possible

🐛 Reporting Issues

Good bug reports help us fix problems faster!

Before Reporting

1. Search existing issues to avoid duplicates
2. Test on latest version to ensure it's not already fixed
3. Gather information about your setup and the problem

Creating a Good Issue Report

Use this template:

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Load script '...'
2. Trigger event '...'
3. See error

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened.

**Environment:**
- AzerothCore version: [e.g., commit hash]
- ALE version: [e.g., commit hash]
- Lua version: [e.g., LuaJIT, Lua 5.2]
- OS: [e.g., Ubuntu 20.04]

**Script/Code:**
```lua
-- Minimal script that reproduces the issue
local function OnLogin(event, player)
    -- problematic code
end
RegisterPlayerEvent(3, OnLogin)

Error messages:

Paste any error messages from the log here

Additional context Any other information that might be helpful.

## 📖 Improving Documentation

Documentation is crucial for helping users understand ALE.

### What to Document

- **API Functions**: Descriptions, parameters, return values, examples
- **Events**: When they trigger, what parameters they pass
- **Best Practices**: Common patterns and anti-patterns
- **Examples**: Real-world use cases and complete scripts

### Documentation Workflow

1. Fork the repository
2. Edit documentation files in the `docs/` folder
3. Use clear, concise language
4. Add code examples where helpful
5. Test any code examples you include
6. Submit a Pull Request

### Markdown Tips

```markdown
# Use headers for structure

## Subsections help organize content

**Bold** for emphasis

`code` for inline code

```lua
-- Code blocks for examples

Tip

Use callouts for important information

• Lists
• Keep
• Things
• Organized

## 🎮 Creating Scripts

Share your scripts with the community!

### Where to Share

- **Discord**: [ALE Community](https://discord.com/invite/bx3y5Qmy)
- **GitHub Discussions**: For detailed explanations
- **Pull Requests**: Add example scripts to the repository

### Script Quality Guidelines

Good example scripts should:

1. **Be Well Commented**: Explain what the code does
2. **Handle Edge Cases**: Check for nil values, validate input
3. **Follow Best Practices**: Use local variables, cache data, etc.
4. **Include Usage Instructions**: How to install and configure
5. **Be Self-Contained**: Include all necessary code

### Example Template

```lua
--[[
Script Name: Player Welcome System
Description: Sends customized welcome message based on player level
Author: YourName
Version: 1.0
Date: 2025-01-09

Installation:
1. Place this file in lua_scripts folder
2. Configure MESSAGES table below
3. Restart server

Features:
- Different messages for different level ranges
- Personalized with player name
- Configurable message tiers
]]

-- Configuration
local MESSAGES = {
    [1] = "Welcome to the server, %s! Enjoy your adventure!",
    [10] = "Welcome back, %s! You've grown stronger!",
    [60] = "Greetings, veteran %s! The endgame awaits!",
    [80] = "Welcome, champion %s! You've mastered your class!"
}

-- Get appropriate message for player level
local function GetWelcomeMessage(player)
    local level = player:GetLevel()
    local message = MESSAGES[1]  -- Default message

    -- Find highest tier message player qualifies for
    for minLevel, msg in pairs(MESSAGES) do
        if level >= minLevel then
            message = msg
        end
    end

    return string.format(message, player:GetName())
end

-- Event handler
local function OnLogin(event, player)
    if not player then
        return
    end

    local message = GetWelcomeMessage(player)
    player:SendBroadcastMessage(message)
end

-- Register the event
RegisterPlayerEvent(3, OnLogin)  -- PLAYER_EVENT_ON_LOGIN

🔨 Development Guidelines

Project Structure

mod-ale/
├── src/
│   └── LuaEngine/          # Core ALE source code
│       ├── docs/           # Source documentation
│       ├── methods/        # API method implementations
│       └── hooks/          # Event hook implementations
├── docs/                   # User-facing documentation
├── conf/                   # Configuration file templates
└── README.md              # Project overview

Branch Strategy

• master: Stable, production-ready code
• feature/: New features (e.g., feature/add-new-hook)
• fix/: Bug fixes (e.g., fix/player-null-check)
• docs/: Documentation updates (e.g., docs/update-install-guide)

Pull Request Guidelines

Good PR:

• Single, focused change
• Clear title and description
• Links related issues
• Passes compilation
• Includes documentation updates if needed

PR Template:

## Description
Brief description of the changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement

## Testing
Describe how you tested your changes

## Related Issues
Fixes #123
Related to #456

## Checklist
- [ ] Code compiles without errors
- [ ] Tested on a running server
- [ ] Updated documentation
- [ ] Followed code style guidelines

---

🌟 Acknowledgements

ALE is built upon the foundation of the Eluna Lua Engine. We acknowledge and thank the Eluna team for their pioneering work in Lua scripting for World of Warcraft server emulators.

• Original Eluna Repository
• Eluna Discord Community

---

_{Developed with ❤️ by the AzerothCore and ALE community}

Thank you for contributing! 🎉

⬆ Back to Top