Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
226 lines (174 loc) · 5.69 KB

CONTRIBUTING.md

File metadata and controls

226 lines (174 loc) · 5.69 KB
Raw

Contributing to ITC

Thank you for your interest in contributing to Information Transform Compression! We welcome contributions from the community.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue on GitHub with:

  • A clear description of the problem
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Your environment (Python version, OS, dependencies)
  • Any relevant code or error messages

Suggesting Features

We love new ideas! For feature requests, please open an issue describing:

  • The problem you're trying to solve
  • Your proposed solution
  • Any alternative approaches you've considered
  • How it fits with ITC's information-theoretic philosophy

Pull Requests

  1. Fork the repository and create a new branch from main

    git checkout -b feature/your-feature-name

  2. Make your changes

    • Write clear, documented code
    • Follow the existing code style
    • Add tests for new functionality
    • Update documentation as needed

  3. Test your changes

    # Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_information_analysis.py -v

# Check code formatting (optional)
black --check .
flake8 .

  4. Commit your changes

    • Use clear, descriptive commit messages
    • Reference related issues (e.g., "Fixes #123")
    git commit -m "Add feature: Per-layer learning rate in quantization"

  5. Push and create a Pull Request

    git push origin feature/your-feature-name

    Then open a PR on GitHub with:

    • Clear description of changes
    • Motivation and context
    • How you tested the changes
    • Screenshots/examples if applicable

Code Style Guidelines

  • Python: Follow PEP 8 style guide
  • Docstrings: Use Google-style docstrings
  • Type hints: Add type annotations for function parameters
  • Comments: Explain why, not what (code should be self-explanatory)

Example:

def compute_idm(
    entropy: float,
    sensitivity: float,
    redundancy: float,
    size: int
) -> float:
    """
    Compute Information Density Metric.
    
    Args:
        entropy: Shannon entropy in bits (0-8 typical range)
        sensitivity: Sensitivity score (0-1)
        redundancy: Redundancy score (0-1)
        size: Number of parameters
    
    Returns:
        idm: Information density metric (higher = more important)
    
    Formula:
        IDM = (Entropy × Sensitivity) / (Size × (1 + Redundancy))
    """
    # Implementation...

Areas We Need Help

High Priority:

  • TensorFlow/JAX parser implementations
  • Additional model architectures (T5, BART, Vision Transformers)
  • Hardware-specific optimizations (CUDA, Intel, ARM)
  • Calibration dataset utilities
  • Accuracy evaluation benchmarks

Medium Priority:

  • Visualization tools for information flow
  • Documentation improvements
  • Tutorial notebooks
  • Example models and use cases
  • Performance profiling tools

Research Contributions:

  • Novel information metrics beyond entropy/sensitivity/redundancy
  • Improved precision allocation algorithms
  • Layer-wise adaptive compression strategies
  • Quantization-aware training integration
  • Neural architecture search with IDM guidance

Testing

All contributions must include tests:

# tests/test_new_feature.py
import pytest
from my_module import new_function

def test_new_function_basic():
    """Test basic functionality."""
    result = new_function(input_data)
    assert result == expected_output

def test_new_function_edge_cases():
    """Test edge cases and error handling."""
    with pytest.raises(ValueError):
        new_function(invalid_input)

Documentation

Update documentation for any user-facing changes:

  • Update README.md for new features
  • Add docstrings to all functions/classes
  • Update SYSTEM_REPORT.md for architecture changes
  • Add examples to demonstrate usage

Commit Message Format

Use clear, imperative commit messages:

Add feature: Per-channel quantization for Conv2d layers

- Implement per-channel scale/zero-point calculation
- Add tests for different tensor shapes
- Update documentation with examples
- Fixes #45

Types:

  • Add: New feature
  • Fix: Bug fix
  • Update: Improvements to existing features
  • Docs: Documentation only
  • Test: Test-related changes
  • Refactor: Code restructuring without functionality changes

Development Setup

  1. Clone the repository

    git clone https://github.com/makangachristopher/Information-Transform-Compression.git
cd Information-Transform-Compression

  2. Create a virtual environment

    python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

  3. Install in development mode

    pip install -e .
pip install pytest black flake8  # Development dependencies

  4. Run tests to verify setup

    pytest tests/ -v

Communication

  • GitHub Issues: For bugs, features, and questions
  • Pull Requests: For code contributions
  • Discussions: For general questions and ideas

Code of Conduct

We are committed to providing a welcoming and inclusive environment:

  • Be respectful and constructive
  • Focus on what is best for the community
  • Show empathy towards others
  • Accept constructive criticism gracefully
  • Give credit where it's due

License

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

Questions?

If you have questions about contributing, feel free to:

  • Open a GitHub Discussion
  • Comment on related issues
  • Reach out to the maintainers

Thank you for contributing to ITC! 🎉