Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
168 lines (123 loc) · 4.41 KB

CONTRIBUTING.md

File metadata and controls

168 lines (123 loc) · 4.41 KB

Contributing to GraphFlow

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

Development Setup

  1. Clone the repository:
git clone https://github.com/UnicoLab/GraphFlow.git
cd graphflow
  1. Set up development environment:
python setup_dev.py

This will:

  • Install the package in development mode
  • Install development dependencies
  • Run code formatting and type checking
  • Run the test suite
  • Validate the project structure

Development Workflow

Code Style

We use the following tools for code quality:

  • Black for code formatting
  • isort for import sorting
  • mypy for type checking
  • pytest for testing

Run these tools before submitting:

# Format code
black graphflow/ tests/ examples/

# Sort imports
isort graphflow/ tests/ examples/ --profile black

# Type checking
mypy graphflow/ --ignore-missing-imports

# Run tests
pytest tests/ -v --cov=graphflow

Testing

We maintain comprehensive test coverage. When adding new features:

  1. Write tests first (TDD approach recommended)
  2. Test both happy path and edge cases
  3. Include integration tests for complex features
  4. Maintain >90% test coverage

Run tests:

# Run all tests
pytest tests/ -v

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

# Run specific test file
pytest tests/test_core.py -v

Adding New Features

  1. Create an issue describing the feature
  2. Fork the repository and create a feature branch
  3. Implement the feature with tests
  4. Update documentation as needed
  5. Submit a pull request

Architecture Guidelines

When contributing to GraphFlow, please follow these architectural principles:

Context System

  • Automatic parameter detection should be the default
  • Manual specification should be available as an override
  • Type hints should be used for better parameter resolution

Node Design

  • Pure functions are preferred when possible
  • Side effects should be clearly documented
  • Error handling should be robust and informative

Pipeline Engine

  • DAG validation must be maintained
  • Dependency detection should be automatic where possible
  • Execution order must respect dependencies

Executor System

  • Pluggable architecture for different backends
  • Resource management should be handled properly
  • Error recovery should be implemented

Pull Request Process

  1. Update documentation for any new features
  2. Add tests for new functionality
  3. Ensure all tests pass locally
  4. Update CHANGELOG.md with your changes
  5. Submit PR with clear description

PR Checklist

  • Code follows style guidelines (black, isort)
  • Type hints are provided
  • Tests are added/updated
  • Documentation is updated
  • All tests pass
  • No breaking changes (or clearly documented)

Code Organization

graphflow/
├── core/              # Core framework components
│   ├── context.py     # Context management system
│   ├── dataset.py     # Dataset abstraction
│   ├── decorators.py  # Node decorators
│   ├── pipeline.py    # Pipeline engine
│   └── executors.py   # Execution backends
├── cli/               # Command-line interface
├── patterns/          # Pre-built processing patterns
├── integrations/      # External system integrations
└── utils/             # Utility functions

tests/                 # Test suite
examples/              # Usage examples
docs/                  # Documentation

Documentation

  • Docstrings should follow Google style
  • Type hints are required for public APIs
  • Examples should be included in docstrings
  • README should be updated for major features

Release Process

  1. Update version in pyproject.toml and __init__.py
  2. Update CHANGELOG.md with release notes
  3. Create release tag following semantic versioning
  4. Publish to PyPI (maintainers only)

Getting Help

  • GitHub Issues for bug reports and feature requests
  • GitHub Discussions for questions and ideas
  • Discord/Slack (links in README) for real-time chat

Code of Conduct

Please be respectful and inclusive in all interactions. We follow the standard open source code of conduct.

License

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