easyqemu/CONTRIBUTING.md

Contributing to EasyQEMU

Thank you for your interest in contributing to EasyQEMU! This document provides guidelines for contributing to the project.

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers and help them get started
• Focus on constructive feedback
• Respect differing viewpoints and experiences

How to Contribute

Reporting Bugs

If you find a bug, please create an issue with:

1. Description: Clear description of the bug
2. Steps to Reproduce: Detailed steps to reproduce the issue
3. Expected Behavior: What you expected to happen
4. Actual Behavior: What actually happened
5. Environment:
   • OS and version
   • QEMU version (qemu-system-x86_64 --version)
   • EasyQEMU version (easyqemu version)
6. Logs: Relevant error messages or logs

Suggesting Features

Feature suggestions are welcome! Please create an issue with:

1. Use Case: Why is this feature needed?
2. Proposed Solution: How should it work?
3. Alternatives: What alternatives have you considered?
4. Examples: Example commands or usage

Pull Requests

1. Fork the Repository

   git clone https://github.com/yourusername/easyqemu.git
   cd easyqemu
   

2. Create a Branch

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix
   

3. Make Your Changes

   • Follow the coding style (see below)
   • Test your changes thoroughly
   • Update documentation if needed

4. Test Your Changes

   # Test basic functionality
   ./easyqemu vm create --name test
   ./easyqemu vm list
   ./easyqemu vm delete test -f
   
   # Test new features
   # Add specific tests for your changes
   

5. Commit Your Changes

   git add .
   git commit -m "feat: add new feature" # or "fix: resolve bug"
   

   Commit message format:

   • feat: for new features
   • fix: for bug fixes
   • docs: for documentation changes
   • style: for formatting changes
   • refactor: for code refactoring
   • test: for test additions
   • chore: for maintenance tasks

6. Push and Create PR

   git push origin feature/your-feature-name
   

   Then create a Pull Request on GitHub with:

   • Clear title and description
   • Reference to related issues
   • Screenshots/examples if applicable

Coding Style

Bash Style Guide

1. Indentation: 4 spaces (no tabs)

2. Function Names: Use snake_case

   vm_create() {
       # ...
   }
   

3. Variable Names: Use UPPER_CASE for constants, snake_case for variables

   DEFAULT_MEMORY="2048"
   local vm_id="test"
   

4. Comments: Use comments for complex logic

   # Parse command line arguments
   while [[ $# -gt 0 ]]; do
       # ...
   done
   

5. Error Handling: Always check for errors

   [[ -z "$vm_id" ]] && fatal "VM ID is required"
   

6. Quoting: Always quote variables

   echo "$variable"  # Good
   echo $variable    # Bad
   

7. Command Substitution: Use $(command) instead of backticks

   local result=$(some_command)  # Good
   local result=`some_command`   # Bad
   

Documentation

• Update README.md for new features
• Add examples to EXAMPLES.sh
• Include inline comments for complex code
• Update help text in the main script

Testing

Before submitting:

1. Syntax Check

   bash -n easyqemu
   

2. ShellCheck (if available)

   shellcheck easyqemu
   

3. Functional Tests

   • Test VM operations (create, start, delete)
   • Test volume operations
   • Test snapshot operations
   • Test repository operations

4. Edge Cases

   • Missing parameters
   • Invalid inputs
   • Non-existent VMs/volumes
   • Permission issues

Areas for Contribution

High Priority

• Windows VM support (UEFI boot)
• Better error messages
• Progress bars for long operations
• Configuration wizard
• Automated tests

Medium Priority

• Web UI
• Remote VM management
• Cloud-init support
• Network configuration wizard
• Resource monitoring

Low Priority

• Plugin system
• VM templates library
• Backup automation
• Integration with cloud providers

Development Setup

1. Install QEMU

   # Debian/Ubuntu
   sudo apt-get install qemu-system-x86 qemu-utils shellcheck
   
   # Fedora/RHEL
   sudo dnf install qemu-kvm qemu-img ShellCheck
   

2. Clone Repository

   git clone https://github.com/yourusername/easyqemu.git
   cd easyqemu
   

3. Make Executable

   chmod +x easyqemu
   

4. Test

   ./easyqemu help
   ./easyqemu version
   

Release Process

For maintainers:

1. Update version in script
2. Update CHANGELOG.md
3. Create git tag
4. Create GitHub release

Questions?

• Create an issue for questions
• Check existing issues and documentation
• Be patient and respectful

License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to EasyQEMU! 🚀