Contributing to ePLACE

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

Getting Started

  1. Fork the repository on GitHub

  2. Clone your fork locally:

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

  3. Create a branch for your changes:

    git checkout -b feature/your-feature-name

Development Setup

Install development dependencies:

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

# Install external dependencies
mamba install -y bioconda::blast bioconda::pytaxonkit bioconda::iqtree bioconda::mafft

Running Tests

Run the test suite to ensure your changes don’t break existing functionality:

# Run all tests
pytest tests/ -v

# Run specific test modules
pytest tests/test_blast_analysis.py -v
pytest tests/test_taxonomy.py -v
pytest tests/test_workflow.py -v

# Run with coverage
pytest tests/ --cov=eplace_lib --cov-report=html

Code Style

  • Follow PEP 8 style guidelines

  • Use meaningful variable and function names

  • Add type hints to function signatures

  • Write docstrings for all public functions and classes

Docstring Format

Use Google-style docstrings:

def function_name(param1: str, param2: int) -> bool:
    """Brief description of function.

    More detailed description if needed.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        ValueError: When invalid input is provided
    """
    pass

Writing Tests

  • Add tests for new features

  • Ensure tests are independent and can run in any order

  • Use descriptive test names

  • Include both positive and negative test cases

Example test structure:

def test_feature_name():
    """Test that feature works correctly."""
    # Setup
    input_data = create_test_data()

    # Execute
    result = function_under_test(input_data)

    # Assert
    assert result == expected_output

Documentation

  • Update documentation for any new features

  • Add examples to relevant documentation pages

  • Update API documentation if adding new modules or functions

  • Keep README.md up to date

Building Documentation

cd docs
make html

# View documentation
# Open docs/build/html/index.html in your browser

Pull Request Process

  1. Ensure all tests pass

  2. Update documentation as needed

  3. Add a clear description of your changes

  4. Reference any related issues

  5. Request review from maintainers

Pull Request Guidelines

  • Keep changes focused and atomic

  • Write clear commit messages

  • Update CHANGELOG if applicable

  • Ensure CI/CD checks pass

Commit Messages

Write clear, descriptive commit messages:

Short summary (50 chars or less)

More detailed explanation if necessary. Wrap at 72 characters.
Explain the problem that this commit is solving, and why this
approach was chosen.

- Bullet points are okay
- Use present tense ("Add feature" not "Added feature")
- Reference issues and pull requests

Reporting Bugs

When reporting bugs, please include:

  • Operating system and version

  • Python version

  • ePLACE version

  • Steps to reproduce the issue

  • Expected behavior

  • Actual behavior

  • Error messages or logs

  • Minimal reproducible example if possible

Use the GitHub issue tracker: https://github.com/linsalrob/eplace/issues

Feature Requests

We welcome feature requests! Please:

  • Check if the feature has already been requested

  • Clearly describe the feature and its use case

  • Explain why this feature would be useful

  • Provide examples of how it would be used

Code Review Process

All submissions require review. We use GitHub pull requests for this purpose.

  • Maintainers will review your code

  • Address any feedback or requested changes

  • Once approved, your changes will be merged

Areas for Contribution

Some areas where contributions are especially welcome:

  • Bug fixes

  • Documentation improvements

  • Additional test coverage

  • Performance improvements

  • Support for additional BLAST databases

  • New analysis features

  • User interface improvements

Code of Conduct

  • Be respectful and inclusive

  • Welcome newcomers

  • Focus on constructive feedback

  • Assume good intentions

Contact

License

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

Thank You!

Your contributions are greatly appreciated and help make ePLACE better for everyone!