Contributing

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

Getting Started

Fork the Repository

Start by forking the main repository to your GitHub account.

# Clone your fork locally
git clone https://github.com/YOUR-USERNAME/tukuy.git
cd tukuy

Set Up Development Environment

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On Unix or MacOS:
source venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"

Create a Feature Branch

Always create a new branch for your changes:
```
git checkout -b feature/your-feature-name
```

Development Guidelines

Code Style

Tukuy follows these coding standards:

Use PEP 8 style guide for Python code
Use type hints for all function parameters and return values
Document all public functions, classes, and methods with docstrings
Keep line length to a maximum of 100 characters
Use meaningful variable and function names
Write unit tests for all new functionality

Here’s an example of proper style:

from typing import Optional, List

def calculate_average(numbers: List[float]) -> Optional[float]:
    """
    Calculate the average of a list of numbers.

    Args:
        numbers: A list of floating-point numbers

    Returns:
        The average as a float, or None if the list is empty
    """
    if not numbers:
        return None
    return sum(numbers) / len(numbers)

Documentation

All new features should be documented with docstrings
Include examples in docstrings
Keep docstrings up-to-date with code changes
Update the user guide and examples for significant features

Docstring Format

Use the following format for docstrings:

"""
Description:
    A short description of what this function/class does.

Version: v1
Status: Production/Beta/Under Development
Last Updated: YYYY-MM-DD

Args:
    param1 (type): Description of parameter 1
    param2 (type): Description of parameter 2

Returns:
    type: Description of return value

Raises:
    ExceptionType: When and why this exception is raised

Notes:
    Additional information, limitations, or special considerations

Example::

    # Basic example
    result = function(arg1, arg2)
    assert result == expected_value
"""

Testing

All new code should be thoroughly tested:

Write Unit Tests
- Write tests for each new feature or bug fix
- Aim for high code coverage
- Test edge cases and error conditions

Run Tests Locally

# Run all tests
pytest

# Run tests with coverage report
pytest --cov=tukuy tests/

Ensure All Tests Pass

Make sure all tests pass before submitting a pull request.

Creating a Pull Request

Commit Your Changes

Make sure your commits are focused and include clear messages:
```
git add .
git commit -m "Add feature: brief description of what you did"
```

Push to Your Fork

git push origin feature/your-feature-name

Create a Pull Request
- Go to the original repository on GitHub
- Click “Pull Request”
- Select your branch
- Fill in the PR template with details about your changes
Respond to Feedback

Be open to feedback and make requested changes. This is a collaborative process to ensure high-quality code.

Creating New Transformers

When adding new transformers to Tukuy, follow these guidelines:

Choose the Right Location
- Place the transformer in the appropriate module based on its functionality
- Create a new module if it doesn’t fit existing categories

Extend the Base Class

All transformers should extend ChainableTransformer:

from tukuy.base import ChainableTransformer

class MyTransformer(ChainableTransformer[InputType, OutputType]):
    def __init__(self, name: str, **kwargs):
        super().__init__(name)
        # Initialize additional parameters

    def validate(self, value: InputType) -> bool:
        # Validate input
        return isinstance(value, ExpectedType)

    def _transform(self, value: InputType, context=None) -> OutputType:
        # Implement transformation logic
        return transformed_value

Handle Errors Properly
- Use appropriate exception types
- Provide clear error messages
- Include the input value in error messages for debugging
Document Thoroughly
- Include detailed docstrings with examples
- Document parameters, return types, and exceptions
- Explain edge cases and limitations
Test Comprehensively
- Test basic functionality
- Test edge cases
- Test error conditions
- Test chaining with other transformers

Creating New Plugins

To create a new plugin:

Create a Plugin Class

from tukuy.plugins import TransformerPlugin

class MyPlugin(TransformerPlugin):
    def __init__(self):
        super().__init__("my_plugin_name")

    @property
    def transformers(self):
        return {
            'transformer_name': lambda _: MyTransformer('transformer_name'),
            'other_transformer': lambda _: OtherTransformer('other_transformer')
        }

    def initialize(self) -> None:
        super().initialize()
        # Perform initialization tasks

    def cleanup(self) -> None:
        super().cleanup()
        # Perform cleanup tasks

Register Your Transformers

Make sure each transformer is properly registered in the transformers property.
Document Your Plugin
- Explain the purpose of the plugin
- Document each transformer provided by the plugin
- Include examples of how to use the plugin
Test the Plugin
- Test registration and initialization
- Test each transformer
- Test cleanup

Release Process

If you’re a maintainer, follow these steps for releases:

Version Bump

Update the version number in: - VERSION file - setup.py - Any other relevant files
Update Changelog

Add detailed notes about changes, improvements, and bug fixes.

Tag the Release

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

Publish to PyPI

python setup.py sdist bdist_wheel
twine upload dist/*

Update Documentation

Ensure the documentation is updated for the new release.

Community Guidelines

Be Respectful: Treat all contributors with respect and consideration.
Be Constructive: Provide constructive feedback on pull requests.
Be Patient: Not all contributors have the same level of experience.
Be Inclusive: Welcome contributions from everyone, regardless of background.

Thank you for helping to improve Tukuy!