docs: add CONTRIBUTING.md

CONTRIBUTING.md

@@ -0,0 +1,314 @@
+# Contributing to Bond
+
+Thank you for your interest in contributing to Bond! This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Pull Request Process](#pull-request-process)
+- [Code Style](#code-style)
+- [Testing](#testing)
+- [Documentation](#documentation)
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We welcome contributors of all backgrounds and experience levels.
+
+## Getting Started
+
+### Reporting Bugs
+
+Before reporting a bug:
+
+1. Search [existing issues](https://github.com/renbytes/bond-agent/issues) to avoid duplicates
+2. If none exists, [open a new issue](https://github.com/renbytes/bond-agent/issues/new) with:
+   - A clear, descriptive title
+   - Steps to reproduce the issue
+   - Expected vs actual behavior
+   - Python version and OS
+   - Relevant error messages or stack traces
+
+### Suggesting Features
+
+Feature requests are welcome! Please:
+
+1. Check [existing issues](https://github.com/renbytes/bond-agent/issues) for similar requests
+2. Open a new issue describing:
+   - The use case or problem you're solving
+   - Your proposed solution
+   - Any alternatives you've considered
+
+### First-Time Contributors
+
+Look for issues labeled [`good first issue`](https://github.com/renbytes/bond-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for beginner-friendly tasks.
+
+## Development Setup
+
+### Prerequisites
+
+- **Python 3.11+** (3.11 or 3.12 recommended)
+- **uv** package manager ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
+- **Git**
+
+### Setup Steps
+
+```bash
+# 1. Fork the repository on GitHub
+
+# 2. Clone your fork
+git clone https://github.com/YOUR_USERNAME/bond-agent.git
+cd bond-agent
+
+# 3. Add upstream remote
+git remote add upstream https://github.com/renbytes/bond-agent.git
+
+# 4. Install dependencies
+uv sync --group dev
+
+# 5. Install pre-commit hooks
+uv run pre-commit install
+
+# 6. Verify setup
+uv run pytest
+```
+
+## Making Changes
+
+### Branch Naming
+
+Create a branch from `main` with a descriptive name:
+
+```bash
+git checkout main
+git pull upstream main
+git checkout -b type/short-description
+```
+
+Branch types:
+- `feat/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation only
+- `refactor/` - Code refactoring
+- `test/` - Test additions or fixes
+
+### Commit Messages
+
+Write clear, concise commit messages:
+
+```
+type: short description
+
+Longer explanation if needed. Wrap at 72 characters.
+
+- Bullet points are fine
+- Explain what and why, not how
+```
+
+Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+Examples:
+- `feat: add GitHub repository search tool`
+- `fix: handle rate limit errors in GitHub adapter`
+- `docs: add streaming server guide`
+
+## Pull Request Process
+
+1. **Update your branch** with the latest upstream changes:
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+2. **Run all checks** before pushing:
+   ```bash
+   uv run pre-commit run --all-files
+   uv run pytest
+   ```
+
+3. **Push your branch** and open a PR:
+   ```bash
+   git push origin your-branch-name
+   ```
+
+4. **Fill out the PR template** with:
+   - Summary of changes
+   - Link to related issues
+   - Test plan
+
+5. **Address review feedback** promptly
+
+### PR Requirements
+
+- All CI checks must pass
+- Code must be formatted and linted
+- New features require tests
+- Documentation updates for user-facing changes
+
+## Code Style
+
+### Formatting and Linting
+
+Bond uses [Ruff](https://docs.astral.sh/ruff/) for formatting and linting:
+
+```bash
+# Format code
+uv run ruff format src tests
+
+# Lint and auto-fix
+uv run ruff check --fix src tests
+```
+
+### Type Checking
+
+Bond uses strict [mypy](https://mypy.readthedocs.io/) type checking:
+
+```bash
+uv run mypy src/bond
+```
+
+All new code must be fully typed. Key rules:
+- No `Any` types without justification
+- All function parameters and returns typed
+- Use `Protocol` for duck typing
+
+### Pre-commit Hooks
+
+Pre-commit runs automatically on each commit:
+
+```bash
+# Run manually
+uv run pre-commit run --all-files
+```
+
+Hooks:
+1. `ruff format` - Auto-formats code
+2. `ruff check --fix` - Lints and auto-fixes
+3. `mypy` - Type checks
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests with coverage
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/unit/tools/github/test_adapter.py
+
+# Run tests matching a pattern
+uv run pytest -k "github"
+
+# Run with verbose output
+uv run pytest -v
+```
+
+### Writing Tests
+
+- Place tests in `tests/` mirroring the `src/` structure
+- Use `pytest` fixtures for setup
+- Use `respx` for mocking HTTP requests
+- Aim for high coverage on new code
+
+Example test:
+
+```python
+import pytest
+from bond.tools.github import GitHubAdapter
+
+@pytest.fixture
+def adapter():
+    return GitHubAdapter(token="test-token")
+
+async def test_get_repo_returns_info(adapter, respx_mock):
+    respx_mock.get("https://api.github.com/repos/owner/repo").respond(
+        json={"name": "repo", "description": "A test repo"}
+    )
+
+    result = await adapter.get_repo("owner", "repo")
+
+    assert result.name == "repo"
+    assert result.description == "A test repo"
+```
+
+## Documentation
+
+### Building Docs
+
+```bash
+# Install docs dependencies
+uv sync --extra docs
+
+# Serve locally with hot reload
+uv run mkdocs serve
+
+# Build and check for errors
+uv run mkdocs build --strict
+```
+
+### Documentation Guidelines
+
+- Update docs for user-facing changes
+- Use Google-style docstrings
+- Include code examples
+- Keep API reference in `docs/api/` in sync
+
+### Docstring Example
+
+```python
+def get_repo(self, owner: str, repo: str) -> RepoInfo:
+    """Get repository metadata.
+
+    Args:
+        owner: Repository owner (user or organization).
+        repo: Repository name.
+
+    Returns:
+        Repository information including description, stars, and topics.
+
+    Raises:
+        RepoNotFoundError: If the repository doesn't exist.
+        RateLimitedError: If API rate limit is exceeded.
+    """
+```
+
+## Project Structure
+
+```
+src/bond/
+├── __init__.py          # Package exports
+├── agent.py             # BondAgent implementation
+├── utils.py             # StreamHandlers utilities
+├── server/              # HTTP server module
+├── tools/               # Bundled toolsets
+│   ├── github/          # GitHub API tools
+│   ├── githunter/       # Git forensics tools
+│   ├── memory/          # Semantic memory tools
+│   └── schema/          # Schema extraction tools
+└── trace/               # Execution tracing
+```
+
+### Adding a New Toolset
+
+See [Adding Tools](https://renbytes.github.io/bond-agent/development/adding-tools/) for the complete guide.
+
+Each toolset follows this structure:
+
+```
+tools/my_tool/
+├── __init__.py          # Public API exports
+├── _protocols.py        # Protocol definition
+├── _types.py            # Pydantic models
+├── _adapter.py          # Protocol implementation
+└── tools.py             # Tool functions
+```
+
+## Questions?
+
+- Open a [GitHub Discussion](https://github.com/renbytes/bond-agent/discussions) for questions
+- Check the [documentation](https://renbytes.github.io/bond-agent/) for guides
+
+Thank you for contributing!