CONTRIBUTING.md

Contributing to Humigence

Thank you for your interest in contributing to Humigence! This document provides guidelines and information for contributors.

🤝 How to Contribute

Reporting Issues

Before creating an issue, please:

1. Search existing issues to avoid duplicates
2. Check the troubleshooting section in the README
3. Provide detailed information about your environment and the issue

When creating an issue, include:

• Environment: OS, Python version, GPU model, CUDA version
• Steps to reproduce: Clear, numbered steps
• Expected behavior: What should happen
• Actual behavior: What actually happens
• Error messages: Full error logs
• Screenshots: If applicable

Suggesting Features

We welcome feature suggestions! Please:

1. Check the roadmap in the README first
2. Describe the use case and why it would be valuable
3. Provide examples of how it would work
4. Consider implementation complexity

Code Contributions

Getting Started

1. Fork the repository

2. Clone your fork:

   git clone https://github.com/your-username/humigence.git
   cd humigence
   

3. Create a feature branch:

   git checkout -b feature/amazing-feature
   

4. Set up development environment:

   pip install -r requirements.txt
   pip install -e .
   

Development Guidelines

Code Style

• Python: Follow PEP 8 style guidelines
• Line length: 88 characters (Black formatter)
• Imports: Use absolute imports, group by standard library, third-party, local
• Docstrings: Use Google-style docstrings
• Type hints: Use type hints for function parameters and return values

Testing

• Write tests for new features
• Run existing tests before submitting:

  python3 -m pytest tests/
  

• Test on different hardware if possible (single GPU, multi-GPU)

Documentation

• Update README.md if adding new features
• Add docstrings to new functions and classes
• Update type hints for better IDE support
• Include examples in docstrings

Pull Request Process

1. Ensure tests pass:

   python3 -m pytest tests/
   python3 -m flake8 cli/ pipelines/ utils/
   

2. Update documentation if needed

3. Commit your changes:

   git add .
   git commit -m "feat: add amazing feature"
   

4. Push to your fork:

   git push origin feature/amazing-feature
   

5. Create a Pull Request with:

   • Clear title and description
   • Reference any related issues
   • Include screenshots if applicable
   • List any breaking changes

Commit Message Convention

We use conventional commits:

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

Examples:

git commit -m "feat: add multi-GPU training support"
git commit -m "fix: resolve GPU detection issue"
git commit -m "docs: update installation instructions"

🏗️ Development Setup

Prerequisites

• Python 3.8+
• CUDA-compatible GPU
• Git

Local Development

1. Clone and install:

   git clone https://github.com/your-username/humigence.git
   cd humigence
   pip install -r requirements.txt
   pip install -e .
   

2. Set up Unsloth:

   python3 training/unsloth/setup_humigence_unsloth.py
   

3. Run tests:

   python3 -m pytest tests/
   

4. Test CLI:

   python3 cli/main.py
   

Project Structure

humigence/
├── cli/                    # Command-line interface
│   ├── main.py            # Main entry point
│   ├── config_wizard.py   # Configuration wizard
│   └── lora_wizard.py     # LoRA-specific wizard
├── training/              # Training modules
│   └── unsloth/          # Unsloth integration
├── pipelines/             # Training pipelines
├── utils/                 # Utility functions
├── config/                # Configuration files
├── tests/                 # Test files
└── docs/                  # Documentation

🧪 Testing

Running Tests

# Run all tests
python3 -m pytest tests/

# Run specific test file
python3 -m pytest tests/test_gpu_selection.py

# Run with verbose output
python3 -m pytest tests/ -v

# Run with coverage
python3 -m pytest tests/ --cov=cli --cov=pipelines --cov=utils

Writing Tests

• Test files should be named test_*.py
• Test functions should be named test_*
• Use descriptive names for test functions
• Test both success and failure cases
• Mock external dependencies when possible

Example:

def test_gpu_detection_single_gpu():
    """Test GPU detection with single GPU."""
    gpu_count, gpus = detect_gpus()
    assert gpu_count == 1
    assert len(gpus) == 1
    assert gpus[0]['index'] == 0

📝 Documentation

Code Documentation

• Functions: Include docstring with description, parameters, returns, and examples
• Classes: Include docstring with description and usage examples
• Modules: Include module-level docstring

Example:

def detect_gpus():
    """
    Detect available GPUs on the system.
    
    Returns:
        tuple: (gpu_count, gpus) where gpus is a list of dicts
               with 'index', 'name', and 'memory' keys
    
    Example:
        >>> gpu_count, gpus = detect_gpus()
        >>> print(f"Found {gpu_count} GPUs")
    """

README Updates

When adding features, update:

• Features section with new capabilities
• Usage examples with new commands
• Configuration section with new options
• Troubleshooting section with common issues

🐛 Bug Reports

Before Reporting

1. Check existing issues for similar problems
2. Try the latest version from main branch
3. Check troubleshooting section in README
4. Search closed issues for solutions

Bug Report Template

**Bug Description**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Run command '...'
2. Select option '...'
3. See error

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

**Environment**
- OS: [e.g., Ubuntu 20.04]
- Python: [e.g., 3.9.7]
- GPU: [e.g., RTX 5090]
- CUDA: [e.g., 11.8]

**Error Logs**

Paste error logs here

**Additional Context**
Any other context about the problem.

💡 Feature Requests

Before Requesting

1. Check the roadmap in README
2. Search existing issues for similar requests
3. Consider implementation complexity

Feature Request Template

**Feature Description**
A clear description of the feature you'd like to see.

**Use Case**
Describe the problem this would solve or the workflow it would improve.

**Proposed Solution**
Describe how you think this should work.

**Alternatives**
Describe any alternative solutions you've considered.

**Additional Context**
Any other context, mockups, or examples.

🏷️ Release Process

Version Numbering

We use Semantic Versioning:

• MAJOR: Incompatible API changes
• MINOR: New functionality in a backwards compatible manner
• PATCH: Backwards compatible bug fixes

Release Checklist

• All tests pass
• Documentation updated
• CHANGELOG.md updated
• Version bumped in pyproject.toml
• Release notes prepared
• Tag created

📞 Getting Help

• GitHub Issues: For bugs and feature requests
• GitHub Discussions: For questions and general discussion
• Email: [Contact information if available]

🙏 Recognition

Contributors will be recognized in:

• CONTRIBUTORS.md file
• Release notes for significant contributions
• GitHub contributors page

📄 License

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

---

Thank you for contributing to Humigence! 🚀