Skip to content

contributing.md

Latest commit

 

History

History
209 lines (145 loc) · 5.57 KB

contributing.md

File metadata and controls

209 lines (145 loc) · 5.57 KB

Contributing to hyper2kvm

Thank you for your interest in contributing to hyper2kvm!

📦 Repository Locations

hyper2kvm is available on multiple platforms:

Note: All development happens on GitHub. GitLab is an automatic mirror for users who prefer that platform.

🔄 GitLab Mirror Setup

The GitLab repository automatically syncs from GitHub using:

For Maintainers: Mirror Configuration

If you need to set up mirroring on a new repository:

  1. Go to GitLab: Settings → Repository → Mirroring repositories
  2. Add mirror:
    • Git repository URL: https://github.com/hyper2kvm/hyper2kvm.git
    • Mirror direction: Pull
    • Authentication: Use GitHub Personal Access Token with repo scope
  3. Enable: "Mirror only protected branches" (optional)
  4. Click: "Mirror repository"

The mirror will automatically pull changes every 5 minutes.

🚀 Getting Started

Prerequisites

  • Python: 3.10 or higher
  • Operating System: Linux (Fedora/RHEL recommended), macOS, or Windows (WSL)
  • System Dependencies:
    • libguestfs
    • libguestfs-tools
    • qemu-img
    • python3-libguestfs

Development Setup

# Clone the repository
git clone https://github.com/hyper2kvm/hyper2kvm.git
cd hyper2kvm

# Install system dependencies (Fedora/RHEL)
sudo dnf install -y python3-libguestfs libguestfs-tools qemu-img python3-hivex

# Install Python dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/unit/ -v

See BUILDING.md for complete build and development instructions.

📝 Pull Request Guidelines

Before Submitting

  1. Test your changes:

    pytest tests/unit/ -v
make lint

  2. Follow code style:

    • We use ruff for linting and formatting
    • Run make fmt to auto-format
    • Line length: 120 characters

  3. Write clear commit messages:

    feat: Add support for btrfs subvolume detection

- Implement _parse_btrfs_subvol() helper
- Update mount.py to handle subvol= option
- Add tests for subvolume path sanitization

  4. Update documentation if needed

Commit Message Format

We follow Conventional Commits:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Pull Request Process

  1. Fork the repository (if you're not a maintainer)
  2. Create a feature branch: git checkout -b feat/my-feature
  3. Make your changes with clear commits
  4. Push to your fork: git push origin feat/my-feature
  5. Open a Pull Request on GitHub
  6. Address review feedback

Note: Do NOT open PRs on GitLab - it's a read-only mirror. All PRs go to GitHub.

🧪 Testing

Run Tests

# All unit tests
pytest tests/unit/ -v

# With coverage
pytest tests/unit/ --cov=hyper2kvm --cov-report=html

# Specific test file
pytest tests/unit/test_fixers/test_fstab_conversion.py -v

Writing Tests

  • Place tests in tests/unit/ matching the source structure
  • Use descriptive test names: test_bypath_converted_to_uuid_in_stabilize_all_mode
  • Include docstrings explaining what the test validates
  • Use pytest fixtures from tests/conftest.py

🏗️ Architecture

Key components:

  • hyper2kvm/orchestrator/: Main pipeline orchestration
  • hyper2kvm/fixers/: Guest OS fixes (offline and live)
  • hyper2kvm/vmware/: vSphere integration (powered by hypersdk)
  • hyper2kvm/converters/: Disk format conversion
  • hyper2kvm/testers/: Boot testing (QEMU, libvirt)

See 01-Architecture.md for detailed architecture documentation.

🔐 Security

  • Never commit secrets (passwords, API keys, tokens)
  • Use .gitignore for sensitive files
  • Report security issues privately to: ssahani@gmail.com
  • See SECURITY.md for our security policy

📖 Documentation

  • User guides: docs/*.md
  • API documentation: Python docstrings
  • Examples: examples/

When adding features:

  1. Update relevant docs in docs/
  2. Add examples if applicable
  3. Update README.md if it changes installation or quick start

🎨 Code Style

We use ruff for linting and formatting:

# Auto-format code
make fmt

# Check for issues
make lint

# Manual commands
ruff format hyper2kvm/
ruff check --fix hyper2kvm/

Style Guidelines

  • Line length: 120 characters (not 80)
  • Imports: Sorted by ruff
  • Type hints: Use modern syntax (str | None not Optional[str])
  • Docstrings: Use for public functions/classes
  • Comments: Explain "why" not "what"

🤝 Community

📜 License

hyper2kvm is licensed under LGPL-3.0-or-later. By contributing, you agree that your contributions will be licensed under the same license.

See LICENSE for the full license text.

🙏 Thank You!

Every contribution helps make hyper2kvm better for everyone. Whether it's code, documentation, bug reports, or feature requests - we appreciate your help!