Contributing to GapClean

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

Getting Started

Prerequisites

• Python 3.8 or higher
• Git
• pip

Development Setup

1. Fork the repository on GitHub

2. Clone your fork:

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

3. Install in development mode:

   pip install -e ".[dev,docs]"
   

4. Create a branch for your changes:

   git checkout -b feature/your-feature-name
   

Development Workflow

Making Changes

1. Write your code
2. Follow existing code style
3. Add type hints to all functions

4. Keep functions focused and well-documented

5. Write tests

6. Add tests for new functionality
7. Ensure existing tests still pass

8. Aim for >90% code coverage

9. Run tests:

   pytest tests/ -v --cov=gapclean --cov-report=term
   

10. Check types:

    mypy gapclean
    

11. Format code:

    black gapclean tests
    ruff check gapclean tests
    

Testing

We use pytest for testing. All tests must pass before submitting a pull request.

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=gapclean --cov-report=term

# Run specific test file
pytest tests/test_validation.py

# Run specific test
pytest tests/test_validation.py::test_validate_input_file_exists

Code Style

We follow PEP 8 with some modifications:

• Line length: 88 characters (Black default)
• Type hints required for all functions
• Docstrings required for public functions

Automated formatting:

# Format with Black
black gapclean tests

# Lint with Ruff
ruff check gapclean tests

Type Checking

All code must pass mypy type checking:

mypy gapclean

Pull Request Process

1. Update documentation
2. Add docstrings to new functions
3. Update relevant .md files in docs/

4. Update CHANGELOG.md with your changes

5. Ensure tests pass

6. All existing tests must pass
7. New features must have tests

8. Coverage should not decrease

9. Submit your pull request

10. Provide a clear description of changes
11. Reference any related issues

12. Include examples if applicable

13. Code review

14. Address reviewer feedback
15. Make requested changes

16. Keep discussion professional and constructive

17. Merge

18. Maintainers will merge when approved
19. Delete your branch after merge

Coding Guidelines

Function Structure

def function_name(param1: str, param2: int = 5) -> None:
    """
    Brief description of what the function does.

    Args:
        param1: Description of param1
        param2: Description of param2 (default: 5)

    Returns:
        Description of return value (if applicable)

    Raises:
        ErrorType: When this error occurs
    """
    # Implementation
    pass

Error Handling

Use custom exception classes:

from gapclean.gapclean import InputValidationError, AlignmentError

# Validation errors
if not os.path.exists(filepath):
    raise InputValidationError(
        f"\n[ERROR] File not found: {filepath}\n"
        f"  Suggestion: Check the file path and try again."
    )

# Processing errors
if len(seq) != expected_len:
    raise AlignmentError(
        f"\n[ERROR] Sequence length mismatch\n"
        f"  Expected: {expected_len}\n"
        f"  Got: {len(seq)}"
    )

Adding Tests

Create tests in the appropriate file in tests/:

# tests/test_new_feature.py

import pytest
from gapclean.gapclean import new_function, InputValidationError

def test_new_function_success(valid_alignment):
    """Test new function with valid input."""
    result = new_function(valid_alignment)
    assert result is not None

def test_new_function_invalid_input():
    """Test new function with invalid input."""
    with pytest.raises(InputValidationError):
        new_function("invalid")

Documentation

Building Documentation

# Install documentation dependencies
pip install -e ".[docs]"

# Serve locally
mkdocs serve

# Build static site
mkdocs build

Documentation is written in Markdown and built with MkDocs Material.

Adding Documentation Pages

1. Create .md file in docs/ directory
2. Add to navigation in mkdocs.yml
3. Follow existing page structure
4. Include code examples

Release Process

(For maintainers)

1. Update version:
2. Edit gapclean/__init__.py

3. Update CHANGELOG.md

4. Create release commit:

   git add gapclean/__init__.py CHANGELOG.md
   git commit -m "Release v1.0.X"
   git push origin main
   

5. Tag release:

   git tag -a v1.0.X -m "Release v1.0.X"
   git push origin v1.0.X
   

6. GitHub Actions will automatically:

7. Run tests on all platforms
8. Build package
9. Publish to PyPI

Reporting Issues

Bug Reports

Include:

• GapClean version (gapclean --version or import gapclean; print(gapclean.__version__))
• Python version
• Operating system
• Steps to reproduce
• Expected vs. actual behavior
• Error messages (if any)

Feature Requests

Include:

• Use case description
• Why existing features don't solve the problem
• Proposed solution (if any)
• Examples of how it would be used

Community Guidelines

• Be respectful and professional
• Provide constructive feedback
• Help others learn
• Credit others' work
• Follow the code of conduct

Questions?

• GitHub Issues: For bug reports and feature requests
• GitHub Discussions: For questions and general discussion
• Email: [Maintainer email if applicable]

License

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

Acknowledgments

Thank you to all contributors who help make GapClean better!

---

Happy coding!