Thank you for your interest in contributing to Python A2A! This guide will help you get started with developing, testing, and submitting your contributions.

1. Fork the Repository

   Start by forking the Python A2A repository on GitHub.

2. Clone Your Fork

   git clone https://github.com/YOUR-USERNAME/python-a2a.git
   cd python-a2a

3. Set Up the Development Environment

   We recommend using UV for managing the development environment:

   # Create a virtual environment
   uv venv
   
   # Install development dependencies
   uv install -e ".[dev]"

   Alternatively, you can use pip:

   # Create a virtual environment
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   
   # Install development dependencies
   pip install -e ".[dev]"

4. Install Pre-commit Hooks

   pre-commit install

Python A2A follows these code style guidelines:

• Black formatting with 88 character line limit
• isort with Black profile for import ordering
• Flake8 for linting
• mypy for type checking
• Google/NumPy style docstrings

You can run the formatting tools with:

# Format code
make format

# Lint code
make lint

All code should include proper type annotations:

def example_function(param1: str, param2: int = 10) -> bool:
    """Example function demonstrating type annotations.
    
    Args:
        param1: A string parameter
        param2: An integer parameter, defaults to 10
        
    Returns:
        A boolean result
    """
    return len(param1) > param2

Python A2A uses pytest for testing:

# Run all tests
make test

# Run a specific test
pytest tests/test_file.py::TestClass::test_function -v

# Run tests with coverage
make coverage

When adding new features, please include tests that verify the functionality.

1. Create a Branch

   Create a branch for your feature or bugfix:

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bugfix-name

2. Make Your Changes

   Implement your changes following the code style guidelines.

3. Write Tests

   Add tests that cover your changes.

4. Commit Your Changes

   git add .
   git commit -m "Your descriptive commit message"

   Please follow these commit message guidelines:

   • Use present tense ("Add feature" not "Added feature")
   • Use imperative mood ("Move cursor to..." not "Moves cursor to...")
   • Reference issues or PRs when applicable ("Fix #123")

5. Push to Your Fork

   git push origin feature/your-feature-name

6. Submit a Pull Request

   Go to the Python A2A repository and create a new pull request from your branch.

   In your pull request description:

   • Clearly describe what your PR does
   • Reference any related issues
   • Mention any breaking changes
   • Include any additional context that would help reviewers

Documentation is crucial for Python A2A. Please follow these guidelines:

1. Docstrings

   Use Google/NumPy style docstrings:

   def function_name(param1: Type, param2: Type) -> ReturnType:
       """Brief description of the function.
       
       More detailed description if needed.
       
       Args:
           param1: Description of param1
           param2: Description of param2
           
       Returns:
           Description of return value
           
       Raises:
           ExceptionType: When and why this exception is raised
       """
       ...

2. Examples

   Include examples in your docstrings to demonstrate usage:

   def add_numbers(a: int, b: int) -> int:
       """Add two numbers together.
       
       Args:
           a: First number
           b: Second number
           
       Returns:
           Sum of a and b
           
       Examples:
           >>> add_numbers(1, 2)
           3
           >>> add_numbers(-1, 5)
           4
       """
       return a + b

3. Documentation Files

   When adding new features, update the relevant documentation files in the docs/ directory. If your feature warrants a new document, create one and link to it from the appropriate section.

Before opening an issue:

1. Check Existing Issues

   Search the existing issues to see if your issue has already been reported.

2. Use Issue Templates

   Use the appropriate issue template:

   • Bug report
   • Feature request
   • Documentation improvement

3. Provide Details

   For bug reports, include:

   • Python version
   • Python A2A version
   • Operating system
   • Minimal, reproducible example
   • Expected vs. actual behavior
   • Any error messages or tracebacks

The Python A2A release process follows these steps:

1. Version Bump

   Update the version in python_a2a/__init__.py following semantic versioning.

2. Changelog Update

   Update the CHANGELOG.md file with the changes in the new version.

3. Documentation Update

   Make sure the documentation is up-to-date with the new version.

4. Release PR

   Create a PR for the release that includes the version bump and changelog update.

5. Publish Release

   Once the PR is merged, create a new GitHub release with release notes and tag the release with the version number.

By contributing to Python A2A, you agree that your contributions will be licensed under the MIT License that covers the project.

Python A2A follows a Code of Conduct that all contributors are expected to adhere to. Please read it before contributing.

If you need help with contributing:

• Ask questions in GitHub Issues
• Reach out to the maintainers via email
• Join the community discussions

Thank you for contributing to Python A2A!