Contributing Guide

Thank you for your interest in contributing to Macrodata Refinement (MDR)! This guide provides information on how to contribute to the project.

Getting Started

Fork the repository:

Fork the repository on GitHub and clone it locally:

git clone https://github.com/yourusername/macrodata-refinement.git
cd macrodata-refinement

Set up the development environment:

# Using the setup script
./scripts/setup_dev_env.sh

# Or manually
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
pre-commit install

Verify your setup:
```
pytest
```

Development Workflow

Branching Strategy

main: The main branch contains the latest stable code.
dev: Development branch for integrating features before release.
Feature branches: Create branches from dev for new features (naming: feature/your-feature-name).
Fix branches: Create branches from dev for bug fixes (naming: fix/issue-description).

Commit Guidelines

We follow the Conventional Commits specification:

feat: add new feature
fix: correct bug
docs: update documentation
style: formatting changes
refactor: code restructuring without changing functionality
test: add or modify tests
chore: maintenance tasks

Pull Request Process

Create a new branch from dev for your changes.
Make your changes, adhering to the coding standards.
Test your changes with automated tests and manual verification.
Commit your changes following the commit guidelines.
Push your branch to your fork.
Create a Pull Request to the dev branch of the main repository.
Describe your changes in the PR, referencing any relevant issues.
Wait for review and address any feedback.

Coding Standards

Type Safety

MDR strongly emphasizes type safety. All code must include:

Type hints for all function parameters and return values (following PEP 484).
Type validation using assertions, especially for floating-point numbers.

Example:

def calculate_metric(value: float, factor: float = 1.0) -> float:
    """
    Calculate a metric based on the input value and factor.

    Args:
        value: Input value
        factor: Scaling factor (default: 1.0)

    Returns:
        Calculated metric
    """
    assert isinstance(value, float), "value must be a floating-point number"
    assert isinstance(factor, float), "factor must be a floating-point number"

    return value * factor

Testing

All new features must include unit tests.
Tests should be placed in the appropriate directory under tests/.
Run the full test suite before submitting a PR.
Aim for at least 90% test coverage for new code.

Documentation

All public functions, classes, and methods must have docstrings following Google style.
Update the documentation when changing functionality.
Add examples for non-trivial features.

Building Documentation

To build the documentation locally:

Install the documentation dependencies:
```
pip install -e ".[docs]"
```
Build the documentation:
```
cd docs
make html
```

Open the documentation in your browser:

# On macOS
open _build/html/index.html

# On Linux
xdg-open _build/html/index.html

# On Windows
start _build/html/index.html

Release Process

Versioning: We follow Semantic Versioning.
Changelog: All changes are documented in the CHANGELOG.md file.
Releases: New releases are created from the main branch after merging from dev.

Communication

Issues: Create GitHub issues for bugs, feature requests, or questions.
Discussions: Use GitHub Discussions for more open-ended conversations.
Security: Report security vulnerabilities via our security policy.

Thank you for contributing to Macrodata Refinement!