CONTRIBUTING.md

Contributing to undatum

Thank you for your interest in contributing to undatum! This document provides guidelines and instructions for contributing.

Development Setup

Prerequisites

• Python 3.8 or higher
• Git
• pip

Installation

1. Clone the repository:

git clone https://github.com/datacoon/undatum.git
cd undatum

2. Create a virtual environment:

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

3. Install development dependencies:

pip install -e ".[dev]"

Or install manually:

pip install -e .
pip install black ruff mypy pylint pytest pytest-cov pre-commit

Code Style

Formatting

We use black for code formatting with a line length of 100 characters:

black undatum/

Linting

We use ruff for fast linting and pylint for deeper analysis:

ruff check undatum/
pylint undatum/

Type Checking

We use mypy for type checking:

mypy undatum/

Pre-commit Hooks

Install pre-commit hooks to automatically check code before commits:

pre-commit install

Documentation

Docstring Style

We use Google-style docstrings for consistency. Example:

def example_function(param1: str, param2: int = 10) -> bool:
    """Brief description of the function.

    Longer description explaining what the function does, any important
    details about its behavior, and any relevant context.

    Args:
        param1: Description of param1.
        param2: Description of param2 (default: 10).

    Returns:
        Description of return value.

    Raises:
        ValueError: When param1 is invalid.

    Example:
        >>> result = example_function("test", 20)
        >>> print(result)
        True
    """
    pass

Building Documentation

Documentation is built using Sphinx:

cd docs
make html

Testing

Running Tests

Run all tests:

pytest

Run with coverage:

pytest --cov=undatum --cov-report=html

Writing Tests

• Place tests in the tests/ directory
• Test files should be named test_*.py
• Use descriptive test function names: test_function_name_scenario

Pull Request Process

1. Create a branch: Create a feature branch from master

   git checkout -b feature/your-feature-name

2. Make changes: Make your changes following the code style guidelines

3. Run checks: Ensure all checks pass:

   black undatum/
   ruff check undatum/
   mypy undatum/
   pytest

4. Commit: Write clear commit messages following conventional commits:

   feat: add new feature
   fix: fix bug in converter
   docs: update README
   refactor: improve performance
   

5. Push: Push your branch and create a pull request

6. Review: Address any feedback from reviewers

Code Review Guidelines

• All code must be reviewed before merging
• Ensure tests pass and coverage is maintained
• Follow the existing code style
• Add documentation for new features
• Update CHANGELOG.md for user-facing changes

Reporting Issues

When reporting issues, please include:

• Description of the issue
• Steps to reproduce
• Expected behavior
• Actual behavior
• Python version
• undatum version
• Relevant error messages or logs

Questions?

Feel free to open an issue for questions or reach out to the maintainers.