Contributing

Contributing to Entropic Measurement

Thank you for your interest in contributing to the Entropic Measurement project! This guide outlines the guidelines and processes for contributing code, documentation, and other improvements to the project.

Table of Contents

• Getting Started
• Code Style Guidelines
• Submitting Pull Requests
• Code Review Process
• Community Standards
• Reporting Issues
• Development Setup

Getting Started

Prerequisites

Before contributing, ensure you have:

• A GitHub account
• Git installed on your local machine
• Python 3.8+ installed
• Familiarity with the project's purpose and scope

Fork and Clone

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/entropic_measurement.git
   cd entropic_measurement

3. Add the upstream repository:

   git remote add upstream https://github.com/rconstant1/entropic_measurement.git

Code Style Guidelines

Python Code Style

• PEP 8 Compliance: Follow PEP 8 style guidelines
• Line Length: Maximum 88 characters per line (Black formatter standard)
• Imports: Use absolute imports when possible, group imports logically
• Naming Conventions:
  • Variables and functions: snake_case
  • Classes: PascalCase
  • Constants: UPPER_SNAKE_CASE
  • Private methods: prefix with single underscore _private_method

Code Formatting

• Use Black for code formatting:

  black .

• Use isort for import sorting:

  isort .

• Use flake8 for linting:

  flake8 .

Documentation Standards

• Docstrings: Use Google-style docstrings for all public functions and classes
• Type Hints: Include type hints for function parameters and return values
• Comments: Write clear, concise comments explaining complex logic
• README Updates: Update relevant documentation when adding new features

Example docstring format:

def calculate_entropy(data: List[float], method: str = "shannon") -> float:
    """Calculate entropy using the specified method.
    
    Args:
        data: List of numerical values for entropy calculation.
        method: Entropy calculation method ("shannon", "renyi", etc.).
        
    Returns:
        The calculated entropy value.
        
    Raises:
        ValueError: If the method is not supported.
    """

Submitting Pull Requests

Before Submitting

1. Create a Feature Branch:

   git checkout -b feature/your-feature-name

2. Write Tests: Ensure your code includes appropriate unit tests

3. Run the Test Suite: All tests must pass

   python -m pytest

4. Check Code Style: Run linting and formatting tools

5. Update Documentation: Add or update relevant documentation

Pull Request Process

1. Sync with Upstream:

   git fetch upstream
   git rebase upstream/main

2. Push Your Branch:

   git push origin feature/your-feature-name

3. Create Pull Request:

   • Use a clear, descriptive title
   • Include a detailed description of changes
   • Reference any related issues using #issue_number
   • Add appropriate labels

Pull Request Template

When creating a pull request, include:

## Description
Brief description of the changes made.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Other (please describe)

## Testing
- [ ] Tests pass locally
- [ ] New tests added for new functionality
- [ ] Documentation updated

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Breaking changes documented

Code Review Process

Review Timeline

• Initial Response: Within 48 hours
• Full Review: Within 1 week for standard PRs
• Complex Reviews: May take longer, reviewers will communicate timeline

Review Criteria

Reviewers will evaluate:

1. Code Quality:

   • Adherence to style guidelines
   • Code readability and maintainability
   • Proper error handling
   • Performance considerations

2. Testing:

   • Adequate test coverage
   • Test quality and relevance
   • Edge cases covered

3. Documentation:

   • Code is well-documented
   • API documentation updated
   • User-facing changes documented

4. Design:

   • Follows project architecture
   • Minimal, focused changes
   • Backwards compatibility considered

Addressing Review Comments

• Respond to all review comments
• Make requested changes promptly
• Ask for clarification if feedback is unclear
• Mark conversations as resolved when addressed
• Request re-review when ready

Approval Process

• Required Approvals: At least 1 approval from a maintainer
• Merge Requirements: All checks must pass
• Merge Method: Squash and merge for feature branches

Community Standards

Code of Conduct

We are committed to providing a welcoming and inclusive environment. All contributors must adhere to our Code of Conduct.

Communication Guidelines

• Be Respectful: Treat all community members with respect
• Be Constructive: Provide helpful, actionable feedback
• Be Patient: Remember that contributors have varying experience levels
• Be Collaborative: Work together to find the best solutions

Contribution Recognition

• All contributors are recognized in the project's acknowledgments
• Significant contributions may be highlighted in release notes
• Regular contributors may be invited to join the maintainer team

Reporting Issues

Bug Reports

When reporting bugs, include:

• Clear description of the issue
• Steps to reproduce
• Expected vs. actual behavior
• Environment details (OS, Python version, etc.)
• Relevant code snippets or error messages

Feature Requests

For new features:

• Describe the proposed functionality
• Explain the use case and benefits
• Consider implementation complexity
• Discuss potential alternatives

Security Issues

Report security vulnerabilities privately to the maintainers. Do not create public issues for security concerns.

Development Setup

Local Development Environment

1. Install Dependencies:

   pip install -r requirements.txt
   pip install -r requirements-dev.txt

2. Pre-commit Hooks (recommended):

   pre-commit install

3. Run Tests:

   python -m pytest tests/

4. Build Documentation:

   cd docs
   make html

Development Workflow

1. Create feature branch
2. Make changes
3. Run tests and linting
4. Commit changes with clear messages
5. Push and create pull request
6. Address review feedback
7. Merge when approved

Commit Message Format

Use conventional commit format:

type(scope): brief description

Longer description if needed

Closes #issue_number

Types: feat, fix, docs, style, refactor, test, chore

Questions and Support

If you have questions about contributing:

• Check existing issues and discussions
• Create a new issue with the "question" label
• Reach out to maintainers for guidance

Thank you for contributing to Entropic Measurement! Your efforts help make this project better for everyone.