Contributing

Contributing

Thank you for your interest in contributing to BGP Explorer!

Development Setup

1. Clone the Repository

git clone https://github.com/hervehildenbrand/bgp-explorer.git
cd bgp-explorer

2. Install Dependencies

# Install all dependencies including dev tools
uv sync --dev

# Install external tools
uv run bgp-explorer install-deps

3. Set Up API Key

cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=bgp_explorer

# Run specific test file
uv run pytest tests/test_models/test_route.py -v

# Run specific test
uv run pytest tests/test_models/test_route.py::test_function_name -v

Code Style

We use Ruff for linting and formatting.

Run Linter

uv run ruff check src/ tests/

Fix Auto-fixable Issues

uv run ruff check --fix src/ tests/

Check Formatting

uv run ruff format --check src/ tests/

Format Code

uv run ruff format src/ tests/

Pre-Push Checklist

Before pushing changes:

# 1. Run tests
uv run pytest

# 2. Run linter
uv run ruff check src/ tests/

# 3. Check formatting
uv run ruff format --check src/ tests/

The CI pipeline runs both pytest and ruff on every push.

Pull Request Process

1. Fork the Repository

Click "Fork" on GitHub to create your own copy.

2. Create a Feature Branch

git checkout -b feature/your-feature-name

3. Make Your Changes

• Write code following the existing style
• Add tests for new functionality
• Update documentation if needed

4. Run Tests and Linting

uv run pytest
uv run ruff check src/ tests/

5. Commit Your Changes

Use clear, descriptive commit messages:

git commit -m "feat: Add support for new data source"
git commit -m "fix: Handle empty API responses gracefully"
git commit -m "docs: Update installation instructions"

6. Push and Create PR

git push origin feature/your-feature-name

Then open a Pull Request on GitHub.

Code Guidelines

Type Hints

Use type hints for all functions:

async def get_prefix_info(self, prefix: str) -> dict[str, Any]:
    """Get routing information for a prefix.

    Args:
        prefix: IP prefix in CIDR notation.

    Returns:
        Dictionary with routing information.
    """
    ...

Docstrings

Use Google-style docstrings:

def analyze_path(self, routes: list[BGPRoute]) -> dict[str, Any]:
    """Analyze AS paths from a list of routes.

    Args:
        routes: List of BGPRoute objects to analyze.

    Returns:
        Dictionary containing:
            - unique_paths: Number of unique paths
            - avg_length: Average path length
            - upstream_asns: Set of upstream ASNs

    Raises:
        ValueError: If routes list is empty.
    """
    ...

Error Handling

Handle errors gracefully:

try:
    result = await self._ripe_stat.get_bgp_state(prefix)
except Exception as e:
    return f"Error looking up prefix: {str(e)}"

Adding New Tools

To add a new tool for Claude:

1. Add the method to BGPTools in src/bgp_explorer/ai/tools.py
2. Include detailed docstring (Claude reads this)
3. Add to get_all_tools() if conditionally available
4. Add status message to TOOL_DESCRIPTIONS
5. Write tests in tests/

Project Structure

src/bgp_explorer/
├── ai/tools.py      # Add new tools here
├── sources/         # Add new data sources here
├── analysis/        # Add analysis utilities here
├── models/          # Add data models here
└── ...

tests/
├── test_models/     # Model tests
├── test_sources/    # Data source tests
├── test_analysis/   # Analysis tests
└── ...

Reporting Issues

Use GitHub Issues for:

• Bug reports (include reproduction steps)
• Feature requests
• Documentation improvements

Include:

• Python version
• OS and version
• Error messages
• Steps to reproduce

Questions?

• Check existing issues on GitHub
• Read the documentation in this wiki
• Open a discussion on GitHub

License

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