Skip to content

Contributing to Flort

Thank you for your interest in contributing to Flort! This guide will help you get started with development and explain our contribution process.

🚀 Getting Started

Development Setup

  1. Fork and Clone
# Fork the repository on GitHub, then:
git clone https://github.com/yourusername/flort.git
cd flort
  1. Create Virtual Environment
# Create environment
python -m venv venv

# Activate (Linux/macOS)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate
  1. Install Development Dependencies
# Install in development mode
pip install -e .

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

# Install documentation dependencies
pip install -r docs/requirements.txt
  1. Verify Installation
# Test installation
flort --version
python -m pytest tests/ -v

🛠️ Development Workflow

Making Changes

  1. Create Feature Branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description
  1. Make Your Changes

Follow the coding standards and add tests for new functionality.

  1. Test Your Changes
# Run all tests
make test

# Run specific tests
python -m pytest tests/test_specific.py -v

# Test with coverage
python -m pytest tests/ --cov=flort --cov-report=html
  1. Update Documentation
# Update relevant documentation
# docs/usage.md, docs/examples.md, etc.

# Test documentation locally
make docs

# Check documentation build
make docs-build
  1. Commit and Push
git add .
git commit -m "feat: add new filtering option"
git push origin feature/your-feature-name
  1. Create Pull Request

Open a pull request on GitHub with a clear description of your changes.

📋 Contribution Types

🐛 Bug Fixes

  1. Find or Create Issue
  2. Search existing issues

  3. Create new issue with bug report template

  4. Fix the Bug

  5. Write a failing test that reproduces the bug
  6. Fix the bug
  7. Ensure the test now passes

  8. Add regression test if appropriate

  9. Example Bug Fix

# tests/test_bug_fix.py
def test_extension_filtering_bug():
    """Test that extensions with dots are handled correctly."""
    # This test would fail before the fix
    result = parse_extensions([".py", "js"])
    assert result == ["py", "js"]  # Should normalize extensions

✨ New Features

  1. Discussion First
  2. Open a feature request

  3. Discuss the approach before implementing

  4. Implementation Guidelines

  5. Follow existing patterns and architecture
  6. Add comprehensive tests
  7. Update documentation

  8. Consider backward compatibility

  9. Example Feature Addition

# flort/new_feature.py
def new_filtering_option(file_list, criteria):
    """
    New filtering functionality.

    Args:
        file_list: List of file dictionaries
        criteria: Filtering criteria

    Returns:
        Filtered file list
    """
    # Implementation here
    pass

# tests/test_new_feature.py
def test_new_filtering_option():
    """Test the new filtering functionality."""
    # Test implementation
    pass

📖 Documentation

  1. Types of Documentation
  2. Code comments and docstrings
  3. User guides and examples
  4. API documentation

  5. README and setup instructions

  6. Documentation Standards

  7. Use clear, concise language
  8. Include code examples
  9. Update relevant sections
  10. Test documentation builds

🧪 Testing

  1. Test Types
  2. Unit tests for individual functions
  3. Integration tests for workflows
  4. UI tests for interactive features

  5. Performance tests for large files

  6. Writing Tests

# tests/test_example.py
import pytest
from pathlib import Path
from flort.utils import example_function

class TestExampleFunction:
    """Test suite for example_function."""

    def test_basic_functionality(self):
        """Test basic use case."""
        result = example_function("input")
        assert result == "expected_output"

    def test_edge_cases(self):
        """Test edge cases and error conditions."""
        with pytest.raises(ValueError):
            example_function("")

    def test_with_fixtures(self, tmp_path):
        """Test using pytest fixtures."""
        test_file = tmp_path / "test.txt"
        test_file.write_text("content")

        result = example_function(test_file)
        assert result is not None

📏 Coding Standards

Python Style

We follow PEP 8 with some modifications:

# Use snake_case for functions and variables
def process_file_list(file_list):
    processed_count = 0
    return processed_count

# Use descriptive names
def get_filtered_files(extensions, exclude_patterns):
    # Not: get_files(ext, exc)
    pass

# Add type hints where helpful
def count_tokens(text: str) -> int:
    """Count tokens in text."""
    return len(text.split())

# Use docstrings for public functions
def public_function(param: str) -> bool:
    """
    Brief description of what this function does.

    Args:
        param: Description of parameter

    Returns:
        Description of return value

    Example:
        ```python
        result = public_function("value")
        ```
    """
    pass

Code Formatting

We use automated tools for consistent formatting:

# Format code with black
black flort/ tests/

# Sort imports with isort  
isort flort/ tests/

# Check style with flake8
flake8 flort/ tests/

# Type checking with mypy
mypy flort/ --ignore-missing-imports

# Run all checks
make check-all

Commit Messages

Use Conventional Commits:

# Feature addition
git commit -m "feat: add new file filtering option"

# Bug fix
git commit -m "fix: handle empty directory gracefully"

# Documentation
git commit -m "docs: update installation guide"

# Tests
git commit -m "test: add tests for file filtering"

# Refactoring
git commit -m "refactor: simplify path handling logic"

🧪 Testing Guidelines

Test Structure

tests/
├── __init__.py
├── test_utils.py           # Test utility functions
├── test_traverse.py        # Test file discovery
├── test_concatenate.py     # Test file concatenation
├── test_cli.py            # Test command-line interface
├── test_ui.py             # Test interactive UI
└── fixtures/              # Test data and fixtures
    ├── sample_project/
    └── test_files/

Writing Good Tests

# Good test example
def test_file_filtering_with_extensions(tmp_path):
    """Test file filtering with specific extensions."""
    # Setup
    (tmp_path / "main.py").write_text("print('hello')")
    (tmp_path / "style.css").write_text("body { }")
    (tmp_path / "README.md").write_text("# Project")

    # Execute
    file_list = get_paths(
        directories=[str(tmp_path)],
        extensions=['py', 'md']
    )

    # Verify
    files = [f for f in file_list if f['type'] == 'file']
    file_names = [f['path'].name for f in files]

    assert 'main.py' in file_names
    assert 'README.md' in file_names
    assert 'style.css' not in file_names

Test Coverage

Aim for high test coverage, especially for:

  • Core functionality
  • Error handling
  • Edge cases
  • User-facing APIs
# Run tests with coverage
python -m pytest tests/ --cov=flort --cov-report=html

# View coverage report
open htmlcov/index.html

📚 Documentation Guidelines

Code Documentation

def complex_function(param1: str, param2: List[int], param3: bool = False) -> Dict[str, Any]:
    """
    Brief one-line description.

    Longer description explaining the purpose, behavior, and any important
    details about the function.

    Args:
        param1: Description of first parameter
        param2: Description of second parameter  
        param3: Description of optional parameter (default: False)

    Returns:
        Description of return value and its structure

    Raises:
        ValueError: When param1 is empty
        IOError: When file operations fail

    Example:
        ```python
        result = complex_function("input", [1, 2, 3], True)
        print(result['status'])
        ```

    Note:
        Any additional notes or warnings
    """
    pass

User Documentation

  1. Keep it practical - Focus on real-world usage
  2. Include examples - Show working code snippets
  3. Explain why - Not just how, but when and why to use features
  4. Update together - Update docs with code changes

Documentation Testing

# Test documentation builds
make docs-build

# Test documentation locally
make docs

# Check for broken links
make docs-check

🔍 Code Review Process

Submitting Pull Requests

  1. Clear Description
  2. Explain what changes you made and why
  3. Reference any related issues

  4. Include screenshots for UI changes

  5. Checklist Before Submitting

  6. Tests pass locally
  7. New tests added for new functionality
  8. Documentation updated
  9. Code follows style guidelines

  10. Commit messages follow convention

  11. Pull Request Template

## Description
Brief description of changes made.

## Related Issues
Fixes #123

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring

## Testing
- [ ] All tests pass
- [ ] New tests added
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated

Review Process

  1. Automated Checks
  2. Tests must pass
  3. Code style checks

  4. Documentation builds

  5. Human Review

  6. Code quality and clarity
  7. Test coverage and quality
  8. Documentation accuracy

  9. User experience impact

  10. Addressing Feedback

  11. Respond to review comments
  12. Make requested changes
  13. Update based on suggestions

🏗️ Architecture Guidelines

Project Structure

flort/
├── flort/              # Main package
│   ├── __init__.py     # Public API exports
│   ├── cli.py          # Command-line interface
│   ├── traverse.py     # File discovery logic
│   ├── concatenate_files.py  # File processing
│   ├── utils.py        # Utility functions
│   └── ...
├── tests/              # Test suite
├── docs/               # Documentation
└── examples/           # Usage examples

Design Principles

  1. Modularity - Keep functions and classes focused
  2. Testability - Design for easy testing
  3. Extensibility - Allow for future enhancements
  4. User-Friendly - Prioritize user experience
  5. Performance - Consider efficiency for large projects

Adding New Features

  1. Plan the Architecture
  2. Where does the feature fit?
  3. What existing code needs changes?

  4. How will it be tested?

  5. Implement Incrementally

  6. Start with core functionality
  7. Add tests early

  8. Build up complexity gradually

  9. Consider Backward Compatibility

  10. Don't break existing APIs
  11. Deprecate features gracefully
  12. Document breaking changes

🎯 Specific Areas for Contribution

High-Priority Areas

  1. Performance Optimization
  2. Large file handling
  3. Memory usage optimization

  4. Faster file discovery

  5. Platform Support

  6. Windows-specific improvements
  7. macOS compatibility

  8. Linux distribution testing

  9. New File Types

  10. Additional language support
  11. Binary file handling improvements

  12. Custom file processors

  13. User Experience

  14. Interactive UI enhancements
  15. Better error messages
  16. Progress indicators

Good First Issues

Look for issues labeled: - good first issue - help wanted - documentation - tests

🙋 Getting Help

Communication Channels

  1. GitHub Issues - Bug reports and feature requests
  2. GitHub Discussions - Questions and general discussion
  3. Code Reviews - Feedback on pull requests

Questions?

  • Check existing documentation first
  • Search closed issues for similar questions
  • Ask in GitHub Discussions
  • Be specific about what you're trying to do

📜 License

By contributing to Flort, you agree that your contributions will be licensed under the BSD 3-Clause License.

Thank you for contributing to Flort! Every contribution, no matter how small, helps make the project better for everyone. 🎉