Contributing

We welcome contributions to genbank_to! This document provides guidelines for contributing to the project.

Getting Started

Fork the Repository

Fork the repository on GitHub: https://github.com/linsalrob/genbank_to

Clone Your Fork

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

Set Up Development Environment

# Create a virtual environment
python -m venv venv
source venv/bin/activate

# Install in editable mode with test dependencies
pip install -e ".[test]"

Create a Branch

git checkout -b feature/your-feature-name

How to Contribute

Reporting Bugs

If you find a bug, please create an issue on GitHub with:

A clear, descriptive title
Steps to reproduce the bug
Expected behavior
Actual behavior
Your environment (OS, Python version, genbank_to version)
Sample data if possible (or a link to it)

Use our bug report template.

Suggesting Enhancements

We welcome feature requests! Please create an issue with:

A clear description of the feature
Why you think it would be useful
Example use cases
Any relevant examples from other tools

Use our feature request template.

Adding Output Formats

We’re always interested in supporting new output formats! If you’d like to add a new format:

Create an issue describing the format
Provide links to format specifications
Include example input and expected output
If you’ve already implemented it, submit a pull request!

Code Contributions

Making Changes

Write Code
- Follow the existing code style (see Style Guidelines below)
- Keep changes focused and minimal
- Add docstrings to new functions
- Update type hints where applicable

Add Tests

Add tests for your changes in the test/ directory:

def test_new_feature():
    """Test description."""
    # Your test code
    assert expected == actual

Run Tests

# Run all tests
pytest

# Run specific test file
pytest test/test_genbank_to.py

# Run with coverage
pytest --cov=GenBankToLib

Update Documentation

If you’ve added a new feature or changed behavior:
- Update relevant .rst files in docs/
- Add examples to docs/examples.rst
- Update API documentation in docs/api.rst
- Update the README.md if appropriate

Commit Changes

Write clear, descriptive commit messages:

git add .
git commit -m "Add support for XYZ format

- Implement xyz_converter function
- Add tests for XYZ format
- Update documentation with examples"

Push and Create Pull Request
```
git push origin feature/your-feature-name
```
Then create a pull request on GitHub with:
- Clear description of changes
- Link to related issues
- Screenshots if applicable
- Confirmation that tests pass

Style Guidelines

Python Code Style

Follow PEP 8 for Python code
Use 4 spaces for indentation
Maximum line length: 120 characters
Use descriptive variable names

# Good
def genbank_to_format(genbank_file, output_format='fasta'):
    """Convert GenBank file to specified format."""
    pass

# Avoid
def gb2fmt(gbf, fmt='fasta'):
    pass

Docstring Format

Use Google-style docstrings:

def genbank_to_format(gbkf, output_format='fasta', skip_pseudo=True):
    """
    Convert a GenBank file to the specified format.

    Args:
        gbkf (str): Path to the GenBank file.
        output_format (str, optional): Desired output format.
            Default is 'fasta'.
        skip_pseudo (bool, optional): Skip pseudogenes.
            Default is True.

    Returns:
        str: Path to the output file.

    Raises:
        FileNotFoundError: If the GenBank file doesn't exist.
        ValueError: If the output format is not supported.

    Example:
        >>> genbank_to_format('genome.gbk', 'gff3')
        'genome.gff3'
    """
    pass

Testing Guidelines

Writing Tests

Write tests for all new functionality
Use descriptive test names
Test edge cases and error conditions
Keep tests independent and isolated

import pytest
from GenBankToLib import genbank_to_faa

def test_genbank_to_faa_basic():
    """Test basic protein extraction."""
    results = list(genbank_to_faa('test/NC_001417.gbk'))
    assert len(results) > 0
    assert all(len(r) == 3 for r in results)

def test_genbank_to_faa_skip_pseudo():
    """Test that pseudogenes are skipped by default."""
    results_with = list(genbank_to_faa('test/pseudo.gbk', skip_pseudo=False))
    results_without = list(genbank_to_faa('test/pseudo.gbk', skip_pseudo=True))
    assert len(results_with) > len(results_without)

def test_genbank_to_faa_file_not_found():
    """Test error handling for missing file."""
    with pytest.raises(FileNotFoundError):
        list(genbank_to_faa('nonexistent.gbk'))

Test Data

Place test files in the test/ directory
Use small, representative test files
Document the source of test data
Include expected output files when appropriate

Documentation Guidelines

Documentation Structure

Use reStructuredText (.rst) format
Keep documentation up-to-date with code changes
Include practical examples
Link to relevant sections

Building Documentation

Build the documentation locally to check your changes:

cd docs
pip install -r requirements-docs.txt
make html

# View the built documentation
open _build/html/index.html

Documentation Style

Use clear, concise language
Provide code examples
Explain both what and why
Include expected output when helpful

Pull Request Process

Before Submitting
- Ensure all tests pass
- Update documentation
- Check code style
- Rebase on latest main branch
Pull Request Description

Include:
- Summary of changes
- Motivation and context
- Type of change (bug fix, new feature, etc.)
- How to test
- Related issues
Review Process
- Address reviewer feedback
- Keep discussion constructive
- Update PR as needed
- Be patient - maintainers review in their spare time
After Merge
- Delete your branch
- Update your fork
- Celebrate! 🎉

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please be respectful and professional in all interactions.

Be kind and courteous
Respect differing viewpoints
Accept constructive criticism gracefully
Focus on what’s best for the community
Show empathy towards others

Communication

GitHub Issues: Bug reports and feature requests
Pull Requests: Code contributions and discussions
Email: raedwards@gmail.com for security issues or private concerns

Recognition

Contributors are recognized in:

The repository’s contributor list on GitHub
The CITATION.cff file for academic citations
Release notes for significant contributions

Thank You!

Thank you for contributing to genbank_to! Your contributions help make bioinformatics tools more accessible and useful for the research community.

Questions?

If you have questions about contributing, please:

Check existing issues and documentation
Create a new issue with your question
Reach out to the maintainers

We’re here to help!