Skip to content

Latest commit

 

History

History
256 lines (186 loc) · 6.22 KB

File metadata and controls

256 lines (186 loc) · 6.22 KB

Contributing to Pymastra

Thank you for your interest in contributing to Pymastra! We welcome contributions from the community and are excited to see what you'll build.

Getting Started

Prerequisites

  • Python 3.11+
  • Git
  • Basic familiarity with async Python (asyncio)

Setup Development Environment

  1. Clone the repository

    git clone https://github.com/akashs101199/pymastra.git
    cd pymastra
  2. Create a virtual environment

    python3 -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
  3. Install development dependencies

    pip install -e ".[dev]"
  4. Verify installation

    pytest tests/
    mypy pymastra/
    ruff check pymastra/

Development Workflow

Creating a Feature Branch

git checkout -b feature/your-feature-name

Use descriptive branch names:

  • feature/ for new features
  • fix/ for bug fixes
  • docs/ for documentation updates
  • test/ for test improvements

Code Style

We maintain high code quality standards:

  • Type Hints: 100% type coverage required (checked with mypy)
  • Linting: Ruff rules: E, F, I, UP, B, SIM, ANN
  • Line Length: 100 characters max
  • Imports: Organized and sorted (ruff I rule)

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_workflow.py

# Run with coverage
pytest --cov=pymastra

# Run async tests with verbose output
pytest -v

Code Quality Checks

# Type checking
mypy pymastra/ --strict

# Linting
ruff check pymastra/

# Fix linting issues automatically
ruff check pymastra/ --fix

# View test coverage
pytest --cov=pymastra --cov-report=html

Submitting Changes

Before Submitting

  1. Run all checks locally

    pytest
    mypy pymastra/ --strict
    ruff check pymastra/
  2. Update tests - Add tests for any new functionality

    • Tests go in tests/ directory
    • Use pytest and pytest-asyncio for async tests
    • Aim for high coverage on new code
  3. Update documentation

    • Add docstrings to all public functions
    • Update relevant .md files
    • Add examples if introducing a new feature
  4. Update CHANGELOG.md - Document your changes under [Unreleased]

Pull Request Process

  1. Create a descriptive PR title

    • Use format: [type] Short description
    • Types: feat, fix, docs, test, refactor, perf
    • Example: feat: Add webhook retry policies
  2. Write a clear PR description

    • Explain what changed and why
    • Link related issues: Fixes #123
    • Include testing notes
    • Include any breaking changes
  3. Keep commits clean

    • One logical change per commit
    • Write descriptive commit messages
    • Use present tense: "Add feature" not "Added feature"
  4. Ensure tests pass

    • All existing tests must pass
    • Add new tests for new functionality
    • Coverage should not decrease

Example PR Description

## Summary
Adds automatic retry logic with exponential backoff for webhook deliveries.

## Changes
- Added `RetryPolicy` class with configurable backoff strategies
- Webhook registry now accepts retry_policy parameter
- Automatic retries up to 3 times with 2^n second delays
- Added failure tracking and reporting

## Testing
- Added 8 tests covering retry logic and failure scenarios
- Tested with both successful and failed webhook deliveries
- Coverage: 95% on webhook module

## Breaking Changes
None - fully backward compatible with default retry enabled.

Fixes #42

Architecture Guidelines

When making significant changes, understand these core concepts:

Storage Abstraction

  • All storage backends inherit from StorageBackend
  • Implement required async methods: save_run, get_run, list_runs
  • Support JSON serialization for cross-backend compatibility

Event-Driven Architecture

  • Use EventLogger for structured logging
  • Emit events at key points: workflow start, step start, step end, errors
  • Allow external handlers via get_event_logger().add_handler()

Type Safety

  • Use Pydantic models for data validation
  • Avoid Any types - use Union or TypeVar if needed
  • Run mypy --strict for validation

Async-First Design

  • All I/O should be non-blocking
  • Use anyio for cross-platform async utilities
  • Test with pytest-asyncio

Reporting Issues

Bug Reports

Include:

  • Python version and OS
  • Minimal code to reproduce
  • Expected vs actual behavior
  • Error messages and stack traces
  • Pymastra version

Feature Requests

Include:

  • Clear use case or motivation
  • Example code showing desired API
  • Any alternatives considered
  • Estimated implementation complexity

Documentation

Documentation is as important as code. We maintain:

  • README.md - Project overview and quick start
  • GETTING_STARTED.md - Beginner-friendly tutorial
  • PERSISTENCE.md - Storage backend guide
  • DEBUGGING.md - Error handling and troubleshooting
  • Inline docstrings - API documentation
  • examples/ - Working examples for each feature

When adding a feature:

  1. Add docstrings to public APIs
  2. Update relevant .md files
  3. Add or update an example
  4. Update CHANGELOG.md

Release Process

Releases are handled by maintainers but follow this process:

  1. Update version in pyproject.toml and pymastra/__init__.py
  2. Update CHANGELOG.md with release notes
  3. Create git tag: git tag -a vX.Y.Z -m "Release vX.Y.Z"
  4. Build and publish to PyPI: python -m build && twine upload dist/*

Community

  • Issues: Questions, bugs, and feature requests
  • Discussions: Ideas and architecture questions
  • Code of Conduct: See CODE_OF_CONDUCT.md

Getting Help

  • Documentation: Check GETTING_STARTED.md and DEBUGGING.md
  • Examples: See the examples/ directory
  • Issues: Search for similar issues or open a new one
  • Discussions: Start a discussion for questions

Licensing

By contributing to Pymastra, you agree that your contributions will be licensed under the MIT License as per the repository's license.

Questions?

Feel free to:

  • Open an issue with the question label
  • Start a discussion
  • Check existing documentation

Thank you for contributing to Pymastra! 🚀