Thank you for your interest in contributing to Pymastra! We welcome contributions from the community and are excited to see what you'll build.
- Python 3.11+
- Git
- Basic familiarity with async Python (asyncio)
-
Clone the repository
git clone https://github.com/akashs101199/pymastra.git cd pymastra -
Create a virtual environment
python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install development dependencies
pip install -e ".[dev]" -
Verify installation
pytest tests/ mypy pymastra/ ruff check pymastra/
git checkout -b feature/your-feature-nameUse descriptive branch names:
feature/for new featuresfix/for bug fixesdocs/for documentation updatestest/for test improvements
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)
# 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# 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-
Run all checks locally
pytest mypy pymastra/ --strict ruff check pymastra/
-
Update tests - Add tests for any new functionality
- Tests go in
tests/directory - Use
pytestandpytest-asynciofor async tests - Aim for high coverage on new code
- Tests go in
-
Update documentation
- Add docstrings to all public functions
- Update relevant .md files
- Add examples if introducing a new feature
-
Update CHANGELOG.md - Document your changes under [Unreleased]
-
Create a descriptive PR title
- Use format:
[type] Short description - Types:
feat,fix,docs,test,refactor,perf - Example:
feat: Add webhook retry policies
- Use format:
-
Write a clear PR description
- Explain what changed and why
- Link related issues:
Fixes #123 - Include testing notes
- Include any breaking changes
-
Keep commits clean
- One logical change per commit
- Write descriptive commit messages
- Use present tense: "Add feature" not "Added feature"
-
Ensure tests pass
- All existing tests must pass
- Add new tests for new functionality
- Coverage should not decrease
## 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 #42When making significant changes, understand these core concepts:
- All storage backends inherit from
StorageBackend - Implement required async methods:
save_run,get_run,list_runs - Support JSON serialization for cross-backend compatibility
- Use
EventLoggerfor structured logging - Emit events at key points: workflow start, step start, step end, errors
- Allow external handlers via
get_event_logger().add_handler()
- Use Pydantic models for data validation
- Avoid
Anytypes - use Union or TypeVar if needed - Run
mypy --strictfor validation
- All I/O should be non-blocking
- Use
anyiofor cross-platform async utilities - Test with
pytest-asyncio
Include:
- Python version and OS
- Minimal code to reproduce
- Expected vs actual behavior
- Error messages and stack traces
- Pymastra version
Include:
- Clear use case or motivation
- Example code showing desired API
- Any alternatives considered
- Estimated implementation complexity
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:
- Add docstrings to public APIs
- Update relevant .md files
- Add or update an example
- Update CHANGELOG.md
Releases are handled by maintainers but follow this process:
- Update version in
pyproject.tomlandpymastra/__init__.py - Update CHANGELOG.md with release notes
- Create git tag:
git tag -a vX.Y.Z -m "Release vX.Y.Z" - Build and publish to PyPI:
python -m build && twine upload dist/*
- Issues: Questions, bugs, and feature requests
- Discussions: Ideas and architecture questions
- Code of Conduct: See CODE_OF_CONDUCT.md
- 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
By contributing to Pymastra, you agree that your contributions will be licensed under the MIT License as per the repository's license.
Feel free to:
- Open an issue with the
questionlabel - Start a discussion
- Check existing documentation
Thank you for contributing to Pymastra! 🚀