CONTRIBUTING.md

Contributing to AgentConnect

Thank you for your interest in contributing to AgentConnect! We aim to make this project a welcoming space for collaboration and improvement.

Table of Contents

• Code of Conduct
• Getting Started
  • Development Environment
  • First Time Setup
• Development Workflow
  • Creating a Feature
  • CI/CD Workflows
  • Code Style
  • Testing
  • Documentation
  • Git Hooks
• Pull Request Process
• Community

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Development Environment

Required tools:

• Python 3.11 or higher
• Poetry (Python package manager)
• Git
• A code editor (VS Code recommended)
• Make (optional, for using Makefile commands)

First Time Setup

1. Fork the repository on GitHub

2. Clone your fork locally:

   git clone https://github.com/AKKI0511/AgentConnect.git
   cd AgentConnect

3. Set up your development environment:

   # Install Poetry if you haven't already
   curl -sSL https://install.python-poetry.org | python3 -
   
   # Install dependencies
   poetry install --with dev,demo
   
   # Install pre-commit hooks
   poetry run pre-commit install
   # or
   make install-hooks

4. Create a branch for your changes:

   git checkout -b feature/your-feature-name

Development Workflow

Creating a Feature

1. Update your main branch:

   git checkout main
   git pull upstream main

2. Create a feature branch:

   git checkout -b feature/your-feature-name

3. Make your changes:

   • Write tests for new functionality
   • Update documentation as needed
   • Follow the code style guidelines

4. Commit your changes:

   git add .
   git commit -m "feat: add your feature description"

CI/CD Workflows

AgentConnect uses GitHub Actions for continuous integration and deployment:

1. CI Workflow (main.yml):

   • Triggered on pushes to main and pull requests
   • Runs on Ubuntu with Python 3.11 and 3.12
   • Sets up Redis for testing
   • Installs dependencies using Poetry
   • Runs linting with flake8
   • Checks code formatting with black
   • Runs tests with pytest
   • Fails fast if any step fails

2. Documentation Workflow (docs.yml):

   • Triggered on pushes to main and pull requests that modify documentation
   • Builds documentation using Sphinx
   • Deploys to GitHub Pages when merged to main
   • Documentation is available at: https://akki0511.github.io/AgentConnect/

When you submit a pull request, these workflows will automatically run to verify your changes. Make sure all checks pass before requesting a review.

Code Style

We use several tools to maintain code quality:

1. Recommended: Use the Makefile for common development tasks:

   # Format code, run linting, and tests
   make all
   
   # Run only linting
   make lint
   
   # Format code
   make format
   
   # Run tests
   make test
   
   # Run tests with coverage
   make coverage

2. Black for code formatting:

   poetry run black .

3. Flake8 for style guide enforcement:

   poetry run flake8

4. Pylint for code analysis:

   poetry run pylint agentconnect/ tests/ demos/

5. Type hints are required for all functions:

   def example_function(param1: str, param2: int) -> bool:
       return True

Git Hooks

We use pre-commit to automate code quality checks before each commit. The hooks will:

• Format code with Black
• Sort imports with isort
• Check for common issues with flake8
• Ensure documentation is up-to-date

To install the hooks:

# Install pre-commit hooks
poetry run pre-commit install
# or
make install-hooks

To manually run all hooks on all files:

poetry run pre-commit run --all-files
# or
make hooks

Note: The demos/ directory is excluded from pre-commit checks as it contains standalone demo applications that follow different coding standards.

Testing

1. Write tests for your changes:

   # tests/test_your_feature.py
   def test_your_feature():
       result = your_feature()
       assert result == expected_value

2. Run the test suite:

   poetry run pytest

Documentation

1. Update docstrings for any new code:

   def your_function(param1: str, param2: int) -> bool:
       """
       Brief description of function.
   
       Args:
           param1: Description of param1
           param2: Description of param2
   
       Returns:
           bool: Description of return value
   
       Raises:
           ValueError: Description of when this error occurs
       """
       return True

2. Update README.md if you've added new features

3. Add examples to the examples/ directory

4. Update API documentation if needed

Pull Request Process

1. Update the README.md with details of major changes
2. Update the CHANGELOG.md following the Keep a Changelog format
3. Ensure all tests pass and code style checks succeed
4. Submit the PR with a clear title and description
5. Wait for review and address any feedback

Example PR description:

## Description
Brief description of your changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
Describe how you tested your changes

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code follows style guidelines
- [ ] CHANGELOG.md updated

Community

• Join our Discord server
• Follow us on Twitter
• Subscribe to our newsletter

Additional Resources

• Python Style Guide (PEP 8)
• Type Hints Guide (PEP 484)
• Git Commit Message Guidelines
• Semantic Versioning

Thank you for contributing to AgentConnect!