Skip to content

Contributing Guide

This guide explains how to contribute to the Bedrock Swarm framework. We welcome contributions of all kinds, from bug fixes to new features.

Getting Started

  1. Fork the Repository 

    git clone https://github.com/YOUR_USERNAME/bedrock-swarm.git
cd bedrock-swarm

  2. Set Up Development Environment 

    # Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate  # Windows

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

  3. Create Feature Branch 

    git checkout -b feature/your-feature-name

Development Workflow

  1. Code Style
  2. Follow PEP 8
  3. Use type hints
  4. Write docstrings (Google style)

  5. Keep functions focused

  6. Testing

  7. Write unit tests
  8. Include integration tests
  9. Maintain coverage (90%+)

  10. Test edge cases

  11. Documentation

  12. Update API docs
  13. Add examples
  14. Include docstrings
  15. Update changelog

Testing

Run tests with:

# Run all tests
pytest

# Run with coverage
pytest --cov=bedrock_swarm

# Run specific test file
pytest tests/unit/test_agency.py

# Run with verbose output
pytest -v

Documentation

Build documentation with:

# Install documentation dependencies
pip install -e ".[docs]"

# Build documentation
mkdocs build

# Serve documentation locally
mkdocs serve

Code Quality

Maintain code quality with:

# Format code
black .

# Sort imports
isort .

# Check types
mypy .

# Run linter
flake8 .

Pull Request Process

  1. Update Documentation
  2. Add/update API documentation
  3. Update README if needed

  4. Add examples for new features

  5. Run Tests

  6. Ensure all tests pass
  7. Add new tests as needed

  8. Maintain coverage

  9. Update Changelog

  10. Add entry to CHANGELOG.md
  11. Follow Keep a Changelog format

  12. Include PR number

  13. Submit PR

  14. Create detailed description
  15. Link related issues
  16. Request review

Commit Guidelines

Follow conventional commits:

type(scope): description

[optional body]

[optional footer]

Types: - feat: New feature - fix: Bug fix - docs: Documentation - style: Formatting - refactor: Code restructuring - test: Adding tests - chore: Maintenance

Example: 

feat(agency): add thread pooling system

- Implements thread reuse
- Adds configuration options
- Updates documentation

Closes #123

Release Process

  1. Version Bump 

    # Update version in pyproject.toml
# Update CHANGELOG.md
# Create release commit
git commit -m "chore: release v1.2.3"

  2. Create Tag 

    git tag -a v1.2.3 -m "Version 1.2.3"
git push origin v1.2.3

  3. Build Package 

    python -m build

  4. Publish Release 

    python -m twine upload dist/*

Code Review

Guidelines for reviewers:

  1. Code Quality
  2. Clean and readable
  3. Well-documented
  4. Properly tested

  5. Type safe

  6. Architecture

  7. Follows patterns
  8. Maintainable
  9. Performant

  10. Secure

  11. Documentation

  12. Clear and complete
  13. Includes examples
  14. Up to date
  15. Well-structured

Community

  • Issues: Use issue templates
  • Discussions: Use GitHub Discussions
  • Questions: Use issue tracker
  • Security: Report privately

License

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